Introduction:This document explains how the FreeType 2 library performs the low-level and system-specific operations of memory management and i/o access. It is targetted to FreeType hackers, porters and "advanced" developers who want special features like providing their own memory manager or streams. Note that the only system-specific part of the library is a file named "ftsystem.c". Its default implementation is in the directory "freetype2/src/base", even though platform-specific builds may contain a system-specific version in a directory like "freetype2/builds/system".
I. Memory Management
{
You'll notice that:
All current implementations of "ftsystem.c" provide a very simple implementation of the FT_Memory interface by calling directly the standard C alloc, realloc and free. The FreeType source code never invokes directly the function pointers. Rather, it calls FT_Alloc, FT_Realloc and FT_Free functions which are defined in "freetype2/src/base/ftobjs.c". These will not be discussed here. If you want to use your own memory allocator rather than the one provided by your build of FreeType, follow these simple steps:
Notice that you don't need to recompile FreeType 2 to use your own memory manager !!.
II. Streams
1. Basic Stream StructureA stream models the array of bytes found in a font file. FreeType 2 separates streams into two families :
Note that a stream's nature only determines how FreeType accesses its content, not the way it is effectively stored. For example, in the case of a compressed font file, one implementation may choose to uncompress the font in memory, then provide a memory based stream to access it. Another one might chose a disk based stream to perform on-the-fly decompression of the font data. Similarly, the font file can be stored on a local disk, or obtained from a network. This will be completely transparent to FreeType. The stream structure is:
{
The following important things must be noticed here:
2. Stream lifecylesEach FT_Face needs its own stream to access font data. The most common way to create a new FT_Stream object is to call the function FT_New_Face. This function takes a file pathname argument that is used to create a new stream object. This is possible because each implementation of "ftsystem.c" provides a function called FT_New_Stream which takes a file pathname and a FT_Stream pointer as an argument. The function simply opens the file and initialises the stream structure accordingly. It is called by FT_New_Face to create the face's stream object. A stream is only closed when the face is destroyed through FT_Done_Face. Its close field function will then be called. Note that the function should never destroy the FT_Stream.
3. Using your own streamsThere are cases where it is interesting to provide your own stream to create a new face object, rather than rely on the default implementation. For example, a filepathname, which is a C string, might not be useful on a system where files are named with a UTF-16 string or via an i-node number of memory address (for ROM files). For this purpose, the FT_Open_Face is defined. It simply takes a FT_Stream pointer as its second argument, instead of a file pathname (the stream must be allocated and initialised by you, so be careful). Actually, the only thing that FT_New_Face does is create a new stream through FT_New_Stream, then call FT_Open_Face to create the face with it. Note also that you can use the function FT_New_Memory_Face to create a new font face for a memory-based font file, whose address and size can be passed as arguments. The function automatically creates the corresponding memory-based stream and use it to create the face.
III. Thread synchronisation
|