It is targetted to FreeType hackers, or more simply to developers who would like a better understanding of the library's source code.
But an example is certainly more meaningful than anything else:
can easily be replaced with:
Each FT_Get_Short or FT_Get_ULong call will read a big-endian integer from the stream (2 bytes for FT_Get_Short, 4 bytes for FT_Get_ULong) and advance the frame cursor accordingly.
FT_Forget_Frame "releases" the frame from memory
There are several advantages to using frames :
error must be a local variable of type FT_Error, while stream must be a local variable or argument of type FT_Stream;
The macro used to access a frame is ACCESS_Frame(_size_), it will translate to:
Similarly, the macro FORGET_Frame() translates to:
Extracting integers can be performed with the GET_xxx macros, like:
(Note that an Offset is an integer stored with 3 bytes on the file).
All this means that the following code:
Can be replaced with macros by:
Which is clearer. Notice that error and stream must be defined
locally though for this code to work.. !!
FT_Forget_Frame(stream)
GET_Byte() FT_Get_Byte(stream)
GET_Char() ((FT_Char)FT_Get_Byte(stream))
GET_Short() FT_Get_Short(stream)
GET_UShort() ((FT_UShort)FT_Get_Short(stream))
GET_Offset() FT_Get_Offset(stream)
GET_UOffset() ((FT_ULong)FT_Get_Offset(stream))
GET_Long() FT_Get_Long(stream)
GET_ULong() ((FT_ULong)FT_Get_Long(stream))
error = FT_Access_Frame(stream, 2+4+4);
if (error) goto ...
str.value1 = FT_Get_Short(stream);
str.value2 = FT_Get_ULong(stream);
str.value3 = FT_Get_ULong(stream);
FT_Forget_Frame(stream);
if ( ACCESS_Frame( 2+4+4 ) ) goto ...
str.value1 = GET_Short();
str.value2 = GET_ULong();
str.value3 = GET_ULong();
FORGET_Frame();
For example, FT_Read_Short( stream, &error ) reads and returns a 2-byte big-endian short from a stream, and place an error code in the error variable.
Thus, reading a single big-endian integer is shorter than using a frame for it.
Note that there is also the macros READ_xxx() which translate to:
and can be used as in:
when error and stream are already defined locally..