118 lines
3.9 KiB
Plaintext
118 lines
3.9 KiB
Plaintext
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 ---
|