The FreeType Porting Guide
or
Everything you need to know to make FreeType
run on the weirdest system
--------------------------------------------------------------------
Table of Contents
Introduction
I. General design and system modules
II. Memory component API
1. The alloction function: TT_Alloc()
2. The release function: TT_Free()
3. The ALLOC() and ALLOC_ARRAY() macros
4. The MEM_xxxx() macros
III. File component API
1. Streams and their functions
2. Frames and file access
3. Differences in thread support levels
IV. Mutex component API
V. Summary & Advanced concepts
1. Porting summary
2. Exotic filesystems
VI. Troubleshooting
Conclusion
--------------------------------------------------------------------
Introduction
============
The FreeType engine is portable in many ways:
- First, it can be compiled by any ANSI C compliant compiler, which
guarantees the widest possible uses.
- Its default build uses a tiny fraction of the ANSI libc, mainly
for memory management and I/O access, which should be available on
most systems (i.e., malloc(), free(), fopen(), fread(), etc).
- Its design is modular, and allows an implementer to remove all
dependencies on a particular runtime environment, to adapt the
engine to its specific needs. For example, it is possible to use
memory-mapped files on systems which support them.
This document explains the engine's design, presenting the `system'
modules that need to be changed by porters of the library, as well
as how to do it.
Note that this documentation is _very_ detailed, and you may
DIRECTLY JUMP to SECTION V (Summary and advanced concepts) which
gives you a QUICK STEP-BY-STEP GUIDE TO PORTING each component,
without the need to understand all the guts of the TrueType engine.
Several issues are discussed, including the use of exotic font
storage conventions.
--------------------------------------------------------------------
I. General design, and system modules
=====================================
The engine's design is intentionally highly modular. It is made
of several `components', each with its own specific goals. Three
of these play an important role with regards to portability. They
are:
- the memory component:
Found in the files `ttmemory.h' and `ttmemory.c'. It defines
several macros and a few functions used by _all_ other modules
to allocate, release, copy, and move memory blocks.
- the file component:
Found in the files `ttfile.h' and `ttfile.c'. It defines
several types and abstractions (streams, frames), that are used
by _all_ other modules to access font files.
- the mutex component:
This component compiles to a null object if the engine is built
in single-thread mode. Otherwise, for thread-safe and reentrant
builds, the macros and functions it defines are used by the rest
of the engine to protect shared variables.
NOTE:
Because the ANSI libc doesn't provide synchronisation
primitives (synchronisation isn't portable accross platforms),
the default implementation, found in `ttmutex.c', is made of
dummy functions which always return a successful error
condition.
You _need_ to re-define this component for your system if you
decide to make a thread-safe or reentrant build, even if you
use the ANSI libc.
When specializing a component, i.e., rewriting it for your
platform, you should respect a few conventions which are explained
in the following sections. Note also that the system-specific
implementations are usually placed in the
`freetype/lib/arch/<system>' directory. For example:
freetype/lib/arch/unix/ttmmap.c
A Unix-only implementation of ttfile which uses the
memory-mapped file API (this greatly improves the engine's
performance, due to the random access pattern typicals of
glyph data retrieval).
freetype/lib/arch/os2/os2file.c
This is an implementation of ttfile specific to OS/2, which
directly calls the system functions DosOpen(), DosRead(), etc.
The FreeType/2 DLL (a free TrueType font driver for OS/2) also
uses its own memory component which calls a special allocation
routine required in its runtime environment, and also provides
additional statistics that can be displayed by an auxiliary
tool while the driver is running in the system.
We ask you to respect this directory convention. This really needs
a minor Makefile change, and still having the ability to compile the
`default' ttfile and ttmemory will help you debug your specific
ports by easy comparisons.
--------------------------------------------------------------------
II. Memory component API
========================
This section presents the macros and functions defined in
ttmemory.h, and how they should be implemented, if you decide to
rewrite the source file ttmemory.c from scratch. An easier
solution would be to replace the calls to malloc() and free() with
your own functions, though.
1. Allocation routine : TT_Alloc()
----------------------------------
This function is used to allocate blocks of memory, just like
malloc(), but defines a very different interface. Its prototype
is:
TT_Error TT_Alloc( long size, void** p );
[The FreeType source files use abstract data types like `Long' for
all internal functions and `TT_Long' for externally visible
structures. See tttypes.h and freetype.h, respectively.]
We can see that:
- The function returns an error code, and _not_ a pointer. The
reason for this is that your own implementation may perfectly
fail for more than one good reason. For example, it could
detect a corrupted heap, a memory exhaustion or an unusually
large block, and have a different error code for each of these
cases.
If a memory allocation error occurs in a FreeType function, it
is always taken into account (of course, for safety reasons),
but its code is directly sent to the caller. This means that
your own applications and font servers will be able to interpret
these errors and let you handle them appropriately.
- Its second argument is the _address_ of a typeless pointer.
This means the need to typecast it before calling this function.
The macro MEM_Alloc() is defined in ttmemory.h to do it for you,
as well as the `memory extraction' performed by the `&'
operator, so that you can write:
char* buffer;
MEM_Alloc( size, buffer );
instead of
TT_Alloc( size, (void**)&buffer );
Note that the engine _never_ uses this macro directly, but
ALLOC() instead (see below) in order to _always_ test the error
code.
*****************
*** IMPORTANT ***
*****************
- A newly allocated block should _always_ be filled with zeroes!
This is a _very_ strong convention used within all the engine.
It helps greatly to reduce code size, in general. If your
implementation of TT_Alloc() doesn't respect it, you're pretty
certain to build an unrunnable (at best) or (worse) instable
engine! Beware.
2. Release routine: TT_Free()
-----------------------------
This routine is naturally used to release any block created
through TT_Alloc(). Its prototype is:
TT_Error TT_Free( void** P );
We can see that:
- It also returns an error code. Note, however, that the error is
ignored in most, if not all, parts of the engine. This is
because freeing memory usually happens when all necessary work
has been finished, or when something already wrong happened.
- It takes the address of a typeless-pointer, and _not_ the
pointer's value itself. This is used to set the pointer's value
to NULL just after the block was released, which avoids dangling
references in objects. Of course, there is a macro defined to
simplify source writing. One can use FREE() like:
char* buffer;
MEM_Alloc( size, buffer );
.... work ....
FREE( buffer );
/* now `buffer' is set to NULL; the following line will */
/* seg-fault */
a = buffer[0];
*****************
*** IMPORTANT ***
*****************
- The function TT_Free() (and thus the macro FREE()) will accept a
NULL pointer successfully! This means more precisely that the
address of a pointer may have the value NULL; in this case it
will return with a successful error code (TT_Err_Ok == 0).
This convention is also _very_ strong in the engine, and
simplifies both code size and style. One of its primary origin
is the engine's object management which requires the ability to
release an object, be it normal or `partial', with the same
code.
3. The ALLOC() and ALLOC_ARRAY() macros
---------------------------------------
Two macros are also defined to make the FreeType source code
easier to read and understand. Their role is to perform an
allocation, while saving the error condition in an _implicit_
local variable called `error', and returning a boolean which is
set to true in case of error. Their definition is
#define ALLOC( pointer, size ) \
( ( error = MEM_Alloc( pointer, size ) ) != TT_Err_Ok )
and
#define ALLOC_ARRAY( pointer, count, type ) \
( ( error = MEM_Alloc( pointer, \
(count) * sizeof ( type ) ) ) \
!= TT_Err_Ok )
They are always used in `if' statements, and can be chained
together. Here is some example code:
char* buffer1 = 0; /* temporary buffer 1 */
char* buffer2 = 0; /* temporary buffer 2 */
TT_Error error;
...
if ( ALLOC_ARRAY( buffer1, n, TT_F26Dot6 ) ||
ALLOC_ARRAY( buffer2, n, short ) )
goto Fail;
... work ...
Fail:
FREE( buffer2 );
FREE( buffer1 );
return error;
Notes:
- If an error occurs during the first allocation, execution will
jump immediately to the `Fail' label.
- The failure code, which releases the buffers, doesn't need to
differentiate whether the first allocation succeeded or not
(simply because FREE() accepts null pointers with no
problems).
The equivalent code, without macros, would be:
char* buffer1;
char* buffer2;
TT_Error error;
error = TT_Alloc( n * sizeof ( TT_F26Dot6 ),
(void**)&buffer1 );
if ( error ) goto Fail_Buffer1;
error = TT_Alloc( n * sizeof ( short ),
(void**)&buffer2 );
if ( error ) goto Fail_Buffer2;
.... work ....
Fail_Buffer2:
TT_Free( (void**)&buffer2 );
Fail_Buffer1:
TT_Free( (void**)&buffer1 );
Which is a lot less clear about its intents, and uses more special
cases.
4. The MEM_xxxx() macros
------------------------
Finally, three macros are defined to perform some common memory
block operations. Their names are rather explicative:
- MEM_Copy()
Used by the engine to copy one block of data in memory to
another one.
- MEM_Set()
Used to set all bytes of a block of memory to a given value.
- MEM_Move()
Well, guess what ;-)
These operations could have been embedded in functions like
TT_Mem_Copy(), TT_Mem_Set(), and TT_Mem_Move(), but a lot of
compilers are able to inline directly calls to such `intrinsic'
functions as memcpy() and memmove(). Hence, macros make sense
here.
--------------------------------------------------------------------
III. File Component API
=======================
This section describes the file component's API, and the things
that are needed to port it to a specific system. Note that only a
fraction of the source code in `ttfile.c' needs to be rewritten
during a port.
1. Streams and their functions
------------------------------
A stream in FreeType (version 1.x) encapsulates both the
location/naming of a file, and its access. This is due to the
fact that they were originally designed to embed a simple ANSI
`FILE*' file pointer.
This means several things:
- A stream is created and opened via the TT_Open_Stream()
function. It takes, in the default build, a font pathname of
type `char*' that it uses when calling fopen().
- It can be released/closed via the function TT_Close_Stream().
- It embeds a `current file position', just like an ordinary file
descriptor. It is thus seekable, through the function
TT_Seek_File().
- Raw data can be extracted from a stream through TT_Read_File()
and TT_Read_At_File().
However, it has certain properties that differ from a libc `FILE*'
data type:
- Because each face object has its own stream, and because most
operating systems limit the number of opened system resources in
each process, it is more than helpful to be able to `flush' a
stream.
A stream is said to be flushed if the system resource it
contains (like a file descriptor) has been closed. However,
this resource is re-opened automatically when needed.
The function TT_Flush_Stream() is used to flush a stream. If a
stream has been flushed, it is also said to be `asleep'.
- The engine calls TT_Use_Stream() before each new stream access.
With it, the file component is able to awake (or `activate')
streams that are flushed, if needed.
- Consequently, the engine calls TT_Done_Stream() when it has
performed all I/O access. These two APIs (TT_Use_Stream() and
TT_Done_Stream()) let the file component track and manage the
engine's access patterns, and allows it to cache opened streams
more cleverly.
For example, one could implement an LRU list used to track the
`oldest' streams, and only activate the 10 `freshest' ones, thus
limiting the total number of system stream resources used by the
library, independently of the total number of opened faces in
the engine.
2. Frames and file access
-------------------------
In order to resolve endianess and alignment issues, the engine
uses the concept of `frames' to extract data from a TrueType
table.
- A frame is simply a sequence of successive bytes, taken from a
stream from its current position. A frame can only exist within
a stream.
- The function TT_Access_Frame() (ideally) reads its data and
places it into an intermediate buffer, which is later used for
parsing. This function also checks that the whole frame fits
into the original file. For example, it will return an error if
detecting `over-reads' in the file (which can happen if the font
file is broken).
Note that the intermediate buffer disappears in the case of
memory-mapped files.
- Each frame has an internal cursor, which is set to its buffer's
base by the previous function. Note, however, that it differs
from the stream's current position, which has been advanced once
TT_Acess_Frame() is completed.
- Data is extracted from the frame through calls to functions of
the form:
TT_Get_<IntegerType>();
where <IntegerType> can be any of: Byte (unsigned char), Char
(signed char), Short, UShort, Long, or ULong.
Each function returns the integer below the current frame
cursor, and advances the latter in the buffer.
- Finally, when the frame access ends, the engine calls the
TT_Forget_Frame() function, which will release the intermediate
buffer and set the cursor to NULL.
Here is a typical frame read sequence:
/* first - read the next 12-bytes frame in memory */
error = TT_Access_Frame( 12 );
if ( error )
return error;
/* now, extract all data */
object->field1 = TT_Get_Short();
object->field2 = TT_Get_Long();
object->field3 = TT_Get_Char();
object->filed4 = TT_Get_Long();
object->field5 = TT_Get_Byte();
/* done - now release the frame */
TT_Forget_Frame();
/* now perform some checks */
if ( object->field1 == -1 )
return Error_1;
if ( object->field2 > object->field4 )
return Error_2;
*****************
*** IMPORTANT ***
*****************
A few things need to be noticed by porters when they implement
frame loading (i.e. the TT_Access_Frame() function):
- The functions that need to be ported are TT_Access_Frame() and
TT_Forget_Frame(). The TT_Get_XXXX() functions should be left
as is.
- A frame has a state, and must _always_ be released through
TT_Forget_Frame() in case of an error. This means that the
engine will _never_ use code like the following:
error = TT_Access_Frame( 12 );
if ( error )
goto Fail;
object->field1 = TT_Get_Short();
/* now check error and return immediately -- */
/* WITHOUT RELEASING FRAME! ERROR! */
if ( object->field1 == -1 )
goto Fail;
object->field2 = TT_Get_Long();
object->field3 = TT_Get_Char();
object->field4 = TT_Get_Long();
/* check for error, return immediately -- */
/* WITHOUT RELEASING FRAME! ERROR! */
if ( object->field2 > object->field4 )
goto Fail;
/* now release frame */
TT_Forget_Frame();
This means more simply that EACH successful call to
TT_Access_Frame() will ALWAYS be followed by a call to
TT_Forget_Frame()!
- As a consequence of the first rule, and also in order to keep
things simple, NESTING FRAME ACCESSES aren't allowed. For
example, the following code will produce an error:
/* First frame access */
error = TT_Access_Frame( 8 );
if ( error )
goto Fail;
/* read a file offset */
offset = TT_Get_Long();
/* seek and load another frame */
error = TT_File_Seek( stream, offset );
if ( error )
goto Fail;
error = TT_Access_Frame( 4 );
/* The function TT_Access_Frame detects nested calls */
/* and ALWAYS returns TT_Err_Nested_Frame_Access! */
if ( error )
goto Fail;
data1 = TT_Get_Long();
/* release second frame */
TT_Forget_Frame();
/* read next integer from the first frame */
data2 = TT_Get_Long();
/* release first frame */
TT_Forget_Frame();
This simplifies the work that needs to be done wen porting the
TT_Access_Frame() and TT_Forget_Frame() functions.
3. Differences in thread support levels
---------------------------------------
The FreeType library can be built to three distinct thread-support
levels. This section will present each other, and show how this
translates within the ttfile.c source code.
a. Levels
The three levels are
- single thread
No synchronization primitive is used to protect the data in
the file component. Hence, there is only one `current' stream
at any one time. Note, however, that in some cases, more than
one stream may be `active' (or `awakened'); e.g., when using
memory-mapped files, each opened face needs a valid mapping
before it can be used/parsed by the engine.
- thread-safe
The thread safe mode synchronizes concurrent accesses to the
renderer's component through mutexes. For the file component,
this means a single mutex which is `locked' by a call to
TT_Use_Stream(), and `released' by TT_Done_Stream().
As a consequence, there is only one possible `current' stream
when the engine reads files, like in the single thread case.
- re-entrant
In this mode, concurrent accesses are possible on many
components, including ttfile. This means that each
TT_Use_Stream() must _really_ create its own system/ANSI
stream for a single file, and that the file component _cannot_
have any state (only stream objects have!), like a `current
stream' and `current frame'.
This mode must use mutexes to protect all shared variables and
lists from concurrent changes/reads. The only component which
is still serialized in this mode is the scan-line converter
(a.k.a. ttraster).
b. Implementation differences
Because the TrueType engine serves more as a `font format
driver' than a general and high-level text-rendering library, it
has been decided to keep its code as simple and compact as
possible.
This implies some implementation differences between the three
thread modes, which are briefly explained below:
- Single-thread and thread-safe mode can have a state, which
means for ttfile.c, a `current stream' and `current frame'.
- In the reentrant mode, the `state' must be stored in a
thread-local place, which means the stack (or more simply
local function variables).
What follows is that some ttfile functions won't take the same
number of arguments depending on the thread-support mode. Let
uss take the example of frame access and parsing:
In single-thread and thread-safe mode, the current frame is
automatically set by the TT_Access_Frame() function, which only
takes a `size' argument to determine the run of bytes to extract
from the _current_stream_ within ttfile's state.
Moreover, the TT_Get_XXXX() functions extract data from the
current frame, and need no arguments. A simple frame access
then looks like this:
/* read the next 12-bytes frame from the _current_stream_ */
error = TT_Access_Frame( 12 );
if ( error )
return error;
/* now, extract all data from the _current_frame_ */
object->field1 = TT_Get_Short();
object->field2 = TT_Get_Long();
object->field3 = TT_Get_Char();
object->filed4 = TT_Get_Long();
object->field5 = TT_Get_Byte();
/* done - now release the current frame */
TT_Forget_Frame();
In reentrant mode, things are a bit different. The current
stream and current frame must be passed as parameters, and the
code looks like this (notice the new function parameters!):
TT_Frame frame; /* define a local variable to handle */
/* the current frame */
.... /* we suppose we already have a stream variable */
.... /* named `stream' (how surprising ;-) */
/* read the next 12-bytes frame from a given stream */
error = TT_Access_Frame( stream, 12, &frame );
if ( error )
return error;
/* now, extract all data from the given frame */
object->field1 = TT_Get_Short( frame );
object->field2 = TT_Get_Long ( frame );
object->field3 = TT_Get_Char ( frame );
object->filed4 = TT_Get_Long ( frame );
object->field5 = TT_Get_Byte ( frame );
/* done - now release the current frame */
TT_Forget_Frame( frame );
The differences between these two schemes are striking. Though
an `easy' solution would have been to only write the engine in
reentrant-mode, it would have resulted in larger and slightly
slower code, as well as the source a bit more obscure about its
intents and thus harder to maintain. Also, the reentrant
version is only needed in rare cases and environments, and it
wasn't thought as a good idea to complexify _source_ code in
order to comply with rare uses.
The problem is solved within the engine by the use of a set of
carefully selected macros, which help generate both versions
from a _single_ source file.
Moreover, as the macros imitate the non-reentrant syntax (i.e.,
the use of the `stream' and `frame' parameters is implicit to
the macros), the source is kept clear and easy to understand,
even if compiled in re-entrant mode.
The code looks then like the following in the engine:
/* read the next 12-bytes frame from the current stream */
/* assignment of the error code in the local `error' */
/* variable is also implicit to the ACCESS_Frame macro, */
/* and its result is always a boolean (no ANSI warnings) */
if ( ACCESS_Frame( 12 ) )
goto Fail;
/* Now, extract all data from the current frame. */
/* The macros GET_xxxxx use an implicit local `frame' */
/* variable in reentrant mode. */
object->field1 = GET_Short();
object->field2 = GET_Long();
object->field3 = GET_Char();
object->filed4 = GET_Long();
object->field5 = GET_Byte();
/* done - now release the current frame */
FORGET_Frame();
Another advantage of the above code is its `expressiveness' in
the sense that it really describes what is happening during the
frame load, hiding the boring but necessary details required by
error checking and reentrancy. And if the error checks are
within the macros, we are sure we won't forget them because they
are `too boring to code' (one of the reason why `exceptions'
caught so quickly in C++ and Java).
c. Consequences on ttfile
Of course, the macros only hide real differences in
implementation which must be reflected in ttfile.h and ttfile.c.
In order to ease this task, some other macros are used, which
use is reserved for these two files. There are:
STREAM_ARG
STREAM_ARGS
FRAME_ARG
FRAME_ARGS in ttfile.h
CUR_Stream
STREAM_VAR
STREAM_VARS
FRAME_VAR
FRAME_VARS in ttfile.c
All of these macros (with the exception of CUR_Stream) default
to nothing (i.e. a void macro) in single-thread and re-entrant
mode, which only differ from the use of a mutex lock and release
in the functions TT_Use_Stream() and TT_Done_Stream().
CUR_Stream defaults to the file component's current stream,
found in its internal state (as you can guess, it designates the
`current stream').
On the opposite, the macros are used to define additional
function parameters (if a function is called) and arguments (if
calling in a function). For example, the following (fictional)
code:
/* return the size of a given stream */
long Stream_Size( STREAM_ARG )
{
return CUR_Stream.size;
}
expands to:
long Stream_Size()
{
return file_component.current_stream.size;
}
in non-reentrant mode, and to:
long Stream_Size( TT_Stream stream )
{
return (*stream).size;
}
otherwise.
Thus, we can see the following reentrant expansions:
STREAM_ARG --> TT_Stream stream
STREAM_ARGS --> TT_Stream stream, (note the comma)
FRAME_ARG --> TT_Frame frame
FRAME_ARGS --> TT_Frame frame, (note the comma)
STREAM_VAR --> stream
STREAM_VARS --> stream,
FRAME_VAR --> frame
FRAME_VARS --> frame,
They follow these simple rules:
- An XXXX_ARG is used to define a single optional parameter in
a function _prototype_. The parameter is said to be single
if it is not followed by anything, e.g.
long Stream_Size( STREAM_ARG )
- An XXXX_ARGS is the same, followed by a comma, in order to
place other (non-optional) parameters behind, e.g.
TT_Error Stream_Seek( STREAM_ARGS long pos )
- An XXXX_VAR is used, _only_ within ttfile.c, to _call_ a
function having an XXXX_ARG or XXXX_ARGS in its prototype
resp. declaration.
long Stream_Left( STREAM_ARG )
{
return ( Stream_Size( STREAM_VAR ) -
Stream_Pos( STREAM_VAR ) );
}
- An XXXX_VARS is the same, but can be followed by non-optional
parameters.
The macros allow you to write some code independently of the
thread level within ttfile.c.
*****************
*** IMPORTANT ***
*****************
In general, porters should not be concerned about the use of
these macros. One easy way to port is to take the ANSI code in
ttfile.c and modify only the parts that really access the system
(like fopen(), fread(), fseek(), etc).
These details are explained here to make you understand how the
code works, in case you are interested in more elaborate ports.
--------------------------------------------------------------------
IV. Mutex Component API
=======================
As said before, the default library source code uses the ANSI libc
only, and the source code in ttmutex.c only contains dummy
functions which return a successful error condition in all cases.
You thus NEED to specialize it in order to successfully use a
thread-safe or reentrant build. Here is explained what is really
important:
1. The TMutex type
------------------
The engine uses the `TMutex' type defined in ttmutex.h to handle
mutexes. It is only a typedef of a `void*' and should be kept
that way for the fastest porting.
Your job will most probably be to store a system mutex/semaphore
handle or pointer in it.
2. The mutex macros and functions
---------------------------------
The interface file ttmutex.h defines several macros that are used
within the engine to protect all shared variables (like lists)
from concurrent accesses. All macros default to `void' (nothing)
in single thread mode, and to calls to the TT_Mutex_XXXX()
functions in multi-threaded modes.
These functions are:
o TT_Mutex_Create()
Takes a TMutex address as an argument. It should place a NULL
pointer in this output variable in case of failure.
o TT_Mutex_Lock()
It also takes the address of a TMutex as an argument. Used to
lock the mutex/semaphore, of course.
o TT_Mutex_Release()
Guess what ;-) Same interface.
o TT_Mutex_Delete()
Destroys a mutex/semaphore.
3. Redefining the TMutex type
-----------------------------
You can also get rid of the TT_Mutex_xxxx() functions if you want
to use your system's synchronization API. This can be done in two
simple steps:
a. Redefine the TMutex type to suit your system's handle types.
b. Redefine the MUTEX_xxxx() macros in order to call directly your
API in the case of multi-threaded builds.
Both methods (specializing the TT_Mutex_xxx() functions or
redefining the macros) are possible.
--------------------------------------------------------------------------
V. Summary and Advanced Concepts
================================
1. Quick step-by-step guide to porting the system components
------------------------------------------------------------
a. Port the memory component
o Look at the `ttmemory.h' file and change the macros
MEM_Copy(), MEM_Move(), and MEM_Set() to reflect your system's
API providing the equivalent functionality. The reason that
macros instead of functions are used there is that many
compilers are able to inline directly these functions within
your code.
o Look at the `ttmemory.c' file. Replace the single malloc()
call with your own allocation routine, and the single free()
with your own release routine. If your allocator uses more
sophisticated functions, you will probably have to rewrite
more parts of this file. See section I above.
b. Port the mutex component
o Look at the file `ttmutex.c' and specialize each routine to
have it use your system's synchronization API.
o For a more advanced port, you can also directly redefine the
definition of the TMutex type in ttmutex.h, as well as the
macro definitions (like MUTEX_Create(), MUTEX_Lock(), etc.) to
use directly your system's API. The TT_Mutex_xxxx() won't be
necessary then.
c. Port the file component
o For a quick port, look at the following functions and replace
the ANSI libc calls (like fopen(), fclose(), fread(), etc.):
Stream_Activate(), Stream_Deactivate(), TT_Open_Stream(),
TT_Done_Stream(), TT_Seek_File(), TT_Skip_File(),
TT_Read_File(), TT_File_Pos()
o If you plan to use memory-mapped files, you can have a look at
the Unix file component found in
`freetype/lib/arch/unix/ttmmap.c'. It should give you an
indication of what to do.
2. Exotic file systems and font resources
-----------------------------------------
a. Other file naming conventions
The high-level library uses the `TT_Text*' type to define the
type of characters used for a font file's pathname. By default,
it equals to the `char*' type, which allow you to open a face
object with the following call:
error = TT_Open_Face( engine, "c:\fonts\times.ttf", &face );
The implementation of TT_Open_Face() passes directly the
pathname pointer to the internal TT_Open_Stream() function,
located in the file component, which really opens the file.
Some filesystems use different naming conventions, like UTF-16
code, where each character is coded in 16 bits. In order to
help them to use FreeType, all you need to do is the following:
- Define the macro TT_HAVE_TT_TEXT.
- Define the type `TT_Text' to the character type you need, like
'wchar_t' for Unicode.
Note that this should apply when compiling the FreeType library,
as well as WHEN INCLUDING THE FILE `freetype.h' IN YOUR
APPLICATIONS.
If the configuration macro TT_HAVE_TT_TEXT is not defined, the
file `freetype.h' defines TT_Text as `char*'. You can read its
source code to see it more explicitly (look at the very first
lines of the code).
You can also use TT_Text as a pointer to more specific files,
like a simple memory address when the font is located in ROM,
etc.
Just synchronize the definition of TT_Text with the
implementation in ttfile.c!
b. Font Resources
FreeType 2.0 will feature many architectural changes that will
help make porting easier, especially with regards of the file
component.
To do this, it will separate the concepts of a `font resource',
i.e. a file seen as a storage, from a `font stream', i.e. a
file seen as a stream of data. Only the resource related code
will be visible to porters, and it will be much easier to port
(for example, nearly all thread-support levels issues will be
treated internally in the rest of the engine, and will be
invisible to the resource component).
We're sorry for the current design and state, but TT_Stream
started as a simple encapsulation of an ANSI FILE* variable,
before font-specific access patterns made them become what they
now are.
FreeType 2.0 will be a good reason to re-design I/O access more
clearly, and fortunately with more power and flexibility (like
using easily files of different type, ROM-based, memory-mapped,
disk-based, in a single engine).
However, all of this doesn't mean than the current design
doesn't work. It does, so don't hesitate to use it :-)
--------------------------------------------------------------------
VI. Troubleshooting
===================
To be written.
--------------------------------------------------------------------
Conclusion
==========
To be written.
--- end of porting.txt ---