kc3-lang/freetype/docs/design/io-frames.html
-
Show log
Commit
-
Hash : 883df43f
Author :
Date : 2000-05-29T07:30:17
Completely checked and fully formatted.
-
docs/design/io-frames.html
-
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341
<!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"> <title>FreeType 2 Internals - I/O Frames</title> </head> <body text="#000000" bgcolor="#FFFFFF" link="#0000EF" vlink="#51188E" alink="#FF0000"> <h1 align=center> FreeType 2.0 I/O Frames </h1> <h3 align=center> © 2000 David Turner (<a href="mailto:david@freetype.org">david@freetype.org</a>)<br> © 2000 The FreeType Development Team (<a href="http://www.freetype.org">www.freetype.org</a>) </h3> <center> <table width="70%"> <tr><td> <hr> <h2> Introduction </h2> <p>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> <p>It is targeted to FreeType hackers, or more simply to developers who would like a better understanding of the library's source code.</p> <hr> <h2> I. What frames are </h2> <p>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> <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> <p>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> <p>Ensure that there are at least 2+4+4=10 bytes left in the stream.</p> </li> <li> <p>"Preload" (for disk-based streams) 10 bytes from the current stream position.</p> </li> <li> <p>Set the frame "cursor" to the first byte in the frame.</p> </li> </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> <p><tt>FT_Forget_Frame()</tt> "releases" the frame from memory.</p> <p>There are several advantages to using frames:</p> <ul> <li> <p>Single-check when loading tables.</p> </li> <li> <p><em>Making code clearer</em> by providing simple parsing functions <em>while keeping code safe</em> from file over-runs and invalid offsets.</p> </li> </ul> <hr> <h2> II. Accessing and reading a frame with macros </h2> <p>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 often used in the library, and doing this only reduces our typing requirements and make the source code much clearer.</p> <p>Note that <tt>error</tt> must be a local variable of type <tt>FT_Error</tt>, while <tt>stream</tt> must be a local variable or argument of type <tt>FT_Stream</tt>.</p> <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> <font color="blue"> <pre> ( error = FT_Access_Frame( stream, _size_ ) ) != FT_Err_Ok</tt></pre> </font> <p>Similarly, the macro <font color="purple"><b><tt>FORGET_Frame()</tt></b></font> translates to</p> <font color="blue"> <pre> <tt>FT_Forget_Frame( stream )</tt></pre> </font> <p>Extracting integers can be performed with the <tt>GET_xxx()</tt> macros, like</p> <table align=center> <tr valign="top"> <td> <b>Macro name</b> </td> <td> Translation </td> <td> Description </td> </tr> <tr valign="top"> <td> <font color="purple"><tt><b>GET_Byte()</b></tt></font> </td> <td> <font color="blue"><tt>FT_Get_Byte(stream)</tt></font> </td> <td> <p>Reads an 8-bit unsigned byte.</p> </td> </tr> <tr valign="top"> <td> <font color="purple"><tt><b>GET_Char()</b></tt></font> </td> <td> <font color="blue"><tt>(FT_Char)<br> FT_Get_Byte(stream)</tt></font> </td> <td> <p>Reads an 8-bit <em>signed</em> byte.</p> </td> </tr> <tr valign="top"> <td> <font color="purple"><tt><b>GET_Short()</b></tt></font> </td> <td> <font color="blue"><tt>FT_Get_Short(stream)</tt></font> </td> <td> Reads a 16-bit signed big-endian integer. </td> </tr> <tr valign="top"> <td> <font color="purple"><tt><b>GET_UShort()</b></tt></font> </td> <td> <font color="blue"><tt>(FT_UShort)<br> FT_Get_Short(stream)</tt></font> </td> <td> Reads a 16-bit unsigned big-endian integer. </td> </tr> <tr valign="top"> <td> <font color="purple"><tt><b>GET_Offset()</b></tt></font> </td> <td> <font color="blue"><tt>FT_Get_Offset(stream)</tt></font> </td> <td> Reads a 24-bit signed big-endian integer. </td> </tr> <tr valign="top"> <td> <font color="purple"><tt><b>GET_UOffset()</b></tt></font> </td> <td> <font color="blue"><tt>(FT_UOffset)<br> FT_Get_Offset(stream)</tt></font> </td> <td> Reads a 24-bit unsigned big-endian integer. </td> </tr> <tr valign="top"> <td> <font color="purple"><tt><b>GET_Long()</b></tt></font> </td> <td> <font color="blue"><tt>FT_Get_Long(stream)</tt></font> </td> <td> Reads a 32-bit signed big-endian integer. </td> </tr> <tr valign="top"> <td> <font color="purple"><tt><b>GET_ULong()</b></tt></font> </td> <td> <font color="blue"><tt>(FT_ULong)<br> FT_Get_Long(stream)</tt></font> </td> <td> Reads a 32-bit unsigned big-endian integer. </td> </tr> </table> <p>(Note that an <b>Offset</b> is an integer stored with 3 bytes on the file.)</p> <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 );</pre> </font> <p>can be simplified with macros:</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 <tt>error</tt> and <tt>stream</tt> must be defined locally though for this code to work!</p> <hr> <h2> III. Alternatives </h2> <p>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> <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 places an error code in the <tt>error</tt> variable.</p> <p>Thus, reading a single big-endian integer is shorter than using a frame for it.</p> <p>Note that there are also macros <font color="purple"><tt>READ_xxx()</tt></font> which translate to</p> <font color="blue"> <pre> 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>if <tt>error</tt> and <tt>stream</tt> are already defined locally.</p> </td></tr> </table> </center> </body> </html>