From 6afe00774a82c60ea90dc1abefb2b5efd2f53e94 Mon Sep 17 00:00:00 2001 From: David Turner Date: Mon, 17 Jan 2000 19:25:18 +0000 Subject: [PATCH] colored the example source code and corrected some typos --- docs/internals/io-frames.html | 286 ++++++++++++++++++++-------------- 1 file changed, 173 insertions(+), 113 deletions(-) diff --git a/docs/internals/io-frames.html b/docs/internals/io-frames.html index 923085cb5..61ad381ba 100644 --- a/docs/internals/io-frames.html +++ b/docs/internals/io-frames.html @@ -20,76 +20,79 @@ FreeType 2.0 I/O Frames

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

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



 

Introduction:

I. What frames are:

@@ -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:

-

    +
      (error=FT_Access_Frame(stream,_size_)) != FT_Err_Ok. -
    +

- Similarly, the macro FORGET_Frame() translates to: -

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

(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);
    -
+ 
+      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();
    -
+ 
+      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.. !! @@ -162,26 +219,29 @@ FreeType 2.0 I/O Frames

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

    + 

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