TEXT   14

Threads with FreeType

Guest on 19th May 2022 03:20:06 PM

  1. Threads with FreeType
  2. =====================
  3.  
  4.  
  5. The  FreeType  engine  can  now  be compiled  in  thread-safe  mode.
  6. Because  we want  to  keep the  engine  small and  fast, the  thread
  7. protection is simple.   This file gives an overview  of what you can
  8. do, and what you should strictly never do.
  9.  
  10.  
  11. How to enable thread-safe support?
  12.  
  13. A. You must  have a valid  replacement for the  file `lib/ttmutex.c'
  14.    which  calls  your system's  API  to  create,  lock, and  release
  15.    mutexes or semaphores.  The current implementation is a dummy and
  16.    doesn't do anything.
  17.  
  18. B. You      must     re-define      the      configuration     macro
  19.    TT_CONFIG_OPTION_THREAD_SAFE   located  in   `ttconfig.h'.   Then
  20.    recompile.
  21.  
  22.  
  23. IMPORTANT NOTE:
  24.  
  25.   If two threads create and  use their own TT_Engine structure, they
  26.   can freely call the library  concurrently on each of them (as well
  27.   as  all their related  objects), even  in the  non-threaded build.
  28.   The following remarks only  apply to concurrent requests performed
  29.   on a single TT_Engine shared by multiple threads.
  30.  
  31.  
  32. --------------------------------------------------------------------
  33.  
  34. - What you can do:
  35.  
  36.   With the exceptions listed below (in `What you can't do'), you can
  37.   call all  API functions  concurrently with two  different threads.
  38.   This includes:
  39.  
  40.     Creating two or more faces from the same engine (i.e. concurrent
  41.     calls to TT_Open_Face()/TT_Open_Collection()).
  42.  
  43.     Creating  two  or  more  instances  from the  same  face  object
  44.     (i.e. concurrent calls to TT_New_Instance()).
  45.  
  46.     Creating two or more glyph  containers from the same face object
  47.     (i.e. concurrent calls to TT_New_Glyph()).
  48.  
  49.     The same holds for destruction of objects.
  50.  
  51.     Load  two or  more  glyphs  concurrently for  the  same face  or
  52.     instance (i.e. concurrent TT_Load_Glyph() calls).
  53.  
  54.     Render two or  more glyphs at the same time,  in the same engine
  55.     (i.e.   calling  TT_Get_Glyph_Bitmap()/TT_Get_Glyph_Pixmap()  or
  56.     TT_Get_Outline_Bitmap()/TT_GetOutline_Pixmap() concurrently).
  57.  
  58.     NOTE: The  scan-line converter  can only render  one glyph  at a
  59.           time,  for  a   given  TT_Engine.   Concurrent  calls  are
  60.           synchronized through a mutex, though.
  61.  
  62.           If  you  really, _really_,  need  to  generate bitmaps  or
  63.           pixmaps concurrently, create  an additional engine and use
  64.           it   with  TT_Get_Outline_Bitmap()/TT_Get_Outline_Pixmap()
  65.           (you don't  need to create  any object in it,  the outline
  66.           can come from any source too).
  67.  
  68.           This is, however, not recommended (it works perfectly, but
  69.           this  could change  in  the future  for various  technical
  70.           reasons).
  71.  
  72.  
  73. ---------------------------------------------------------------------------
  74.  
  75. - What you cannot do:
  76.  
  77.   - You shouldn't try to delete  an object while still using it with
  78.     another thread.  The engine  doesn't protect you from stupidity!
  79.     For example, these concurrent calls:
  80.  
  81.       TT_Close_Face( face );
  82.       TT_Get_Glyph_Bitmap( glyph, &bitmap );
  83.  
  84.     will act unexpectedly if the glyph is a child of the face (i.e.,
  85.     was created with TT_New_Glyph( face, &glyph ))
  86.                                    ^^^^
  87.                                  same face
  88.  
  89.     Here are some other examples:
  90.  
  91.       TT_Get_Glyph_Outline( glyph1, ... );
  92.       TT_Load_Glyph( instance, glyph1, ... );
  93.  
  94.     or
  95.  
  96.       TT_Get_Outline_BBox( outline, &bbox );
  97.       TT_Transform_Outline( outline );
  98.  
  99.     etc.
  100.  
  101.     You get the  idea: Only the face and  instances are protected --
  102.     glyph containers and outlines should be thread-specific.
  103.  
  104.  
  105.   - You  shouldn't initialize extensions  in an  engine concurrently
  106.     (which is what every mere mortal will do anyway :-).
  107.  
  108.  
  109.  
  110. That's about it. Now enjoy the lib ;-)
  111.  
  112.  
  113. PS: See the  `MT-Note' and  `MT-Safe'  remarks  in ttapi.c  for more
  114.     detailed information on each specific function.
  115.  
  116.  
  117. --- end of threads.txt ---

Raw Paste


Login or Register to edit or fork this paste. It's free.