From 426b20af0295158039376dde713bc9985f57f7ab Mon Sep 17 00:00:00 2001 From: David Turner Date: Tue, 11 Jan 2000 04:59:55 +0000 Subject: [PATCH] Added the new "io-frames.html" document, that describes the frame interface as well as the new READ_xxxx and FT_Read_xxxx functions/macros.. --- docs/internals/io-frames.html | 187 ++++++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 docs/internals/io-frames.html diff --git a/docs/internals/io-frames.html b/docs/internals/io-frames.html new file mode 100644 index 000000000..923085cb5 --- /dev/null +++ b/docs/internals/io-frames.html @@ -0,0 +1,187 @@ + + + + + + + FreeType 2 Internals - I/O Frames + + + + + +
+

+FreeType 2.0 I/O Frames

+ +
+

+© 2000 David Turner (david@freetype.org)
+© 2000 The FreeType Development Team (devel@freetype.org)

+ +


+

+
  +

Introduction:

+ + +

+ +

I. What frames are:

+ + +

+ +

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.. +

+