ref: 20c15add91dc1495ebe80bc12ea7ff62f43046e3
dir: /docs/design/io-frames.html/
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="David Turner">
<meta name="GENERATOR" content="Mozilla/4.5 [fr] (Win98; I) [Netscape]">
<title>FreeType 2 Internals - I/O Frames</title>
</head>
<body>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<center>
<h1>
FreeType 2.0 I/O Frames</h1></center>
<center>
<h3>
© 2000 David Turner (<a href="mailto:[email protected]">[email protected]</a>)<br>
© 2000 The FreeType Development Team (<a href="http://www.freetype.org">www.freetype.org</a>)</h3></center>
<p><br>
<hr WIDTH="100%">
<br>
<h2>Introduction:</h2>
<ul>
This document explains the concept of i/o <b>frames</b> as used in the
FreeType 2 source code. It also enumerates the various functions and macros
that can be used to read them.
<p>
It is targetted to FreeType hackers, or more simply to developers who would
like a better understanding of the library's source code.
</ul>
<p><hr><p>
<h2>I. What frames are:</h2>
<ul>
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.
<p>
But an example is certainly more meaningful than anything else.
The following code:
<p>
<font color="blue"><pre>
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 ...
</pre></font>
can easily be replaced with:
<p>
<font color="blue"><pre>
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);
</pre></font>
<p>
Here, the call to <tt>FT_Access_Frame</tt> will:<p>
<ul>
<li>Ensure that there are at least 2+4+4=10 bytes left in the stream.
<li>"Preload" (for disk-based streams) 10 bytes from the current
stream position.
<li>Set the frame "cursor" to the first byte in the frame;
</ul>
<p>
Each <tt>FT_Get_Short</tt> or <tt>FT_Get_ULong</tt> call will read a
big-endian integer from the stream (2 bytes for <tt>FT_Get_Short</tt>,
4 bytes for <tt>FT_Get_ULong</tt>) and advance the frame cursor accordingly.
<p>
<tt>FT_Forget_Frame</tt> "releases" the frame from memory
<p>
There are several advantages to using frames :<p>
<ul>
<li>single-check when loading tables
<li><em>making code clearer</em> by providing simple parsing functions
<em>while keeping code safe</em> from file over-runs and invalid
offsets.
</ul>
<p>
</ul>
<p><hr><p>
<h2>II. Accessing and reading a frame with macros:</h2>
<ul>
By convention in the FreeType source code, macros are able to use two implicit
variables named "<tt>error</tt>" and "<tt>stream</tt>". 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.
<p>
Note that <tt>error</tt> must be a local variable of type <tt>FT_Error</tt>,<br>
while <tt>stream</tt> must be a local variable or argument of type <tt>FT_Stream</tt>;
<p>
The macro used to access a frame is
<font color="purple"><tt><b>ACCESS_Frame(_size_)</b></tt></font>, it will
translate to:<p>
<ul><font color="blue">
<tt>(error=FT_Access_Frame(stream,_size_)) != FT_Err_Ok</tt>.
</font></ul>
<p>
Similarly, the macro
<font color="purple"><b><tt>FORGET_Frame()</tt></b></font>
translates to:<p>
<ul><font color="blue">
<tt>FT_Forget_Frame(stream)</tt>
</font></ul>
<p>
Extracting integers can be performed with the <tt>GET_xxx</tt> macros, like:<p>
<ul>
<table>
<tr>
<td><b>Macro name</b> <td>Translation <td>Description
<tr><td><font color="purple"><tt><b>
GET_Byte()
</b></tt></font><td><font color="blue"><tt>
(FT_Get_Byte(stream))
</tt></font><td>
reads an 8-bit unsigned byte
<tr><td><font color="purple"><tt><b>
GET_Char()
</b></tt></font><td><font color="blue"><tt>
((FT_Char)FT_Get_Byte(stream))
</tt></font><td>
reads an 8-bit <em>signed</em> byte
<tr><td><font color="purple"><tt><b>
GET_Short()
</b></tt></font><td><font color="blue"><tt>
(FT_Get_Short(stream))
</tt></font><td>
reads a 16-bit signed big-endian integer
<tr><td><font color="purple"><tt><b>
GET_UShort()
</b></tt></font><td><font color="blue"><tt>
((FT_UShort)FT_Get_Short(stream))
</tt></font><td>
reads a 16-bit unsigned big-endian integer
<tr><td><font color="purple"><tt><b>
GET_Offset()
</b></tt></font><td><font color="blue"><tt>
(FT_Get_Offset(stream))
</tt></font><td>
reads a 24-bit signed big-endian integer
<tr><td><font color="purple"><tt><b>
GET_UOffset()
</b></tt></font><td><font color="blue"><tt>
((FT_UOffset)FT_Get_Offset(stream))
</tt></font><td>
reads a 24-bit unsigned big-endian integer
<tr><td><font color="purple"><tt><b>
GET_Long()
</b></tt></font><td><font color="blue"><tt>
(FT_Get_Long(stream))
</tt></font><td>
reads a 32-bit signed big-endian integer
<tr><td><font color="purple"><tt><b>
GET_ULong()
</b></tt></font><td><font color="blue"><tt>
((FT_ULong)FT_Get_Long(stream))
</tt></font><td>
reads a 32-bit unsigned big-endian integer
</table>
</ul>
<p>
(Note that an <b>Offset</b> is an integer stored with 3 bytes on the file).
<p>
All this means that the following code:<p>
<font color="blue"><pre>
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);<br>
</pre></font>
<p>
Can be replaced with macros by:<p>
<font color="blue"><pre>
if ( ACCESS_Frame( 2+4+4 ) ) goto ...
str.value1 = GET_Short();
str.value2 = GET_ULong();
str.value3 = GET_ULong();
FORGET_Frame();
</pre></font>
<p>
Which is clearer. Notice that <b>error</b> and <b>stream</b> must be defined
locally though for this code to work.. !!
</ul>
<p><hr><p>
<h2>III. Alternatives:</h2>
<ul>
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 <font color="blue"><tt>FT_Read_xxxx</tt></font>.
<p>
For example,
<font color="blue"><tt>FT_Read_Short( stream, &error )</tt></font> reads and
returns a 2-byte big-endian integer from a <tt>stream</tt>, and place an
error code in the <tt>error</tt> variable.
<p>
Thus, reading a single big-endian integer is shorter than using a frame
for it.
<p>
Note that there is also the macros
<font color="purple"><tt>READ_xxx()</tt></font> which translate to:<p>
<font color="blue"><pre>
<tt>( FT_Read_xxx(stream,&error), error != FT_Err_Ok )
</pre></font>
<p>
and can be used as in:<p>
<font color="blue"><pre>
if ( READ_UShort(variable1) || READ_ULong (variable2) ) goto Fail;
</pre></font>
<p>
when <b>error</b> and <b>stream</b> are already defined locally..
</ul>