FreeType 2.0 I/O Frames

© 2000 David Turner ([email protected])
© 2000 The FreeType Development Team ([email protected])

Introduction:

frames

It is targetted to FreeType hackers, or more simply to developers who would like a better understanding of the library's source code.

I. What frames are:

But an example is certainly more meaningful than anything else:

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: Ensure that there are at least 2+4+4=10 bytes left in the stream. "Preload" (for disk-based streams) 10 bytes from the current stream position. Set the frame "cursor" to the first byte in the frame; 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 : single-check when loading tables making code clearer by providing simple parsing functions.

II. Accessing and reading a frame with macros: By convention in the FreeType source code, macros are able to use two implicit variables named "error" and "stream". This is useful because 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, 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: (error=FT_Access_Frame(stream,_size_)) != FT_Err_Ok. Similarly, the macro FORGET_Frame() translates to: FT_Forget_Frame(stream) Extracting integers can be performed with the GET_xxx macros, like: 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)) (Note that an Offset is an integer stored with 3 bytes on the file). All this means that the following code: 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); Can be replaced with macros by: if ( ACCESS_Frame( 2+4+4 ) ) goto ... str.value1 = GET_Short(); str.value2 = GET_ULong(); str.value3 = GET_ULong(); FORGET_Frame(); Which is clearer. Notice that error and stream must be defined locally though for this code to work.. !! 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. 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: ( FT_Read_xxx(stream,&error), error != FT_Err_Ok ) and can be used as in: if ( READ_UShort(variable1) || READ_ULong (variable2) ) goto Fail; when error and stream are already defined locally..

`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))

FreeType 2.0 I/O Frames

© 2000 David Turner ([email protected]) © 2000 The FreeType Development Team ([email protected])

Introduction:

I. What frames are:

II. Accessing and reading a frame with macros:

III. Alternatives:

© 2000 David Turner ([email protected])
© 2000 The FreeType Development Team ([email protected])