- It is targetted to FreeType hackers, or more simply to developers who would like - a better understanding of the library's source code. + This document explains the concept of i/o frames as used in the + FreeType 2 source code. It also enumerates the various functions and macros + that can be used to read them. +
+ 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 :
-
+ Simply speaking, a frame is an array of bytes in a font file that is + "preloaded" into memory in order to be rapidly parsed. Frames are useful to + ensure that every "load" is checked against end-of-file overruns, and + provides nice functions to extract data in a variety of distinct formats. +
+ But an example is certainly more meaningful than anything else. + The following code: +
+
+ error = read_short(stream, &str.value1);
+ if (error) goto ...
+
+ error = read_ulong(stream, &str.value2);
+ if (error) goto ...
+
+ error = read_ulong(stream, &str.value3);
+ if (error) goto ...
+
+ can easily be replaced with:
+
+
+ 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);
+
+
+ Here, the call to FT_Access_Frame will:
+
+ 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 :
+
@@ -101,58 +104,112 @@ FreeType 2.0 I/O Frames these two variables are extremely used in the library, and doing this only reduces our typing requirements and make the source code much clearer.
- error must be a local variable of type FT_Error,
+ Note that 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 + 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.. !!
@@ -162,26 +219,29 @@ FreeType 2.0 I/O Frames
- 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..
+ It is sometimes useful to read small integers from a font file without using
+ a frame. Some functions have been introduced in FreeType 2 to do just that,
+ and they are of the form FT_Read_xxxx.
+
+ For example,
+ FT_Read_Short( stream, &error ) reads and
+ returns a 2-byte big-endian integer 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..
+ Similarly, the macro
+ FORGET_Frame()
+ translates to:
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))
+
+ Macro name Translation Description
+
+
+ GET_Byte()
+
+ (FT_Get_Byte(stream))
+
+ reads an 8-bit unsigned byte
+
+
+ GET_Char()
+
+ ((FT_Char)FT_Get_Byte(stream))
+
+ reads an 8-bit signed byte
+
+
+ GET_Short()
+
+ (FT_Get_Short(stream))
+
+ reads a 16-bit signed big-endian integer
+
+
+ GET_UShort()
+
+ ((FT_UShort)FT_Get_Short(stream))
+
+ reads a 16-bit unsigned big-endian integer
+
+
+ GET_Offset()
+
+ (FT_Get_Offset(stream))
+
+ reads a 24-bit signed big-endian integer
+
+
+ GET_UOffset()
+
+ ((FT_UOffset)FT_Get_Offset(stream))
+
+ reads a 24-bit unsigned big-endian integer
+
+
+ GET_Long()
+
+ (FT_Get_Long(stream))
+
+ reads a 32-bit signed big-endian integer
+
+
+ GET_ULong()
+
+ ((FT_ULong)FT_Get_Long(stream))
+
+ reads a 32-bit unsigned big-endian integer
+
- 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);
-
+ 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();
-
+ if ( ACCESS_Frame( 2+4+4 ) ) goto ...
+
+ str.value1 = GET_Short();
+ str.value2 = GET_ULong();
+ str.value3 = GET_ULong();
+
+ FORGET_Frame();
+
III. Alternatives:
- It is sometimes useful to read small integers from a font file without using
- a frame. Some functions have been introduced in FreeType 2 to do just that,
- and they are of the form FT_Read_xxxx.
-
- ( FT_Read_xxx(stream,&error), error != FT_Err_Ok )
-
-
- if ( READ_UShort(variable1) || READ_ULong (variable2) ) goto Fail;
-
-
+ ( FT_Read_xxx(stream,&error), error != FT_Err_Ok )
+
+
+ if ( READ_UShort(variable1) || READ_ULong (variable2) ) goto Fail;
+
+