summaryrefslogtreecommitdiff
path: root/Build/source/libs/freetype/freetype-1.5/docs/threads.txt
diff options
context:
space:
mode:
authorPeter Breitenlohner <peb@mppmu.mpg.de>2009-03-20 07:45:16 +0000
committerPeter Breitenlohner <peb@mppmu.mpg.de>2009-03-20 07:45:16 +0000
commit9c241c5d2d9413361d32567876c35b2b9e2754c9 (patch)
tree754aab0f779c0c574897fb6bd6f67f9d722c9ac2 /Build/source/libs/freetype/freetype-1.5/docs/threads.txt
parent207e0fee56e671a0913674ee3f71701bb9d84768 (diff)
new build system
git-svn-id: svn://tug.org/texlive/trunk@12446 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/libs/freetype/freetype-1.5/docs/threads.txt')
-rw-r--r--Build/source/libs/freetype/freetype-1.5/docs/threads.txt117
1 files changed, 117 insertions, 0 deletions
diff --git a/Build/source/libs/freetype/freetype-1.5/docs/threads.txt b/Build/source/libs/freetype/freetype-1.5/docs/threads.txt
new file mode 100644
index 00000000000..6e157fa3e1a
--- /dev/null
+++ b/Build/source/libs/freetype/freetype-1.5/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 ---