docs/reference/ft2-system_interface.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2 "http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   6 <title>FreeType-2.5.5 API Reference</title>
   7 <style type="text/css">
   8   a:link { color: #0000EF; }
   9   a:visited { color: #51188E; }
  10   a:hover { color: #FF0000; }
  11
  12   body { font-family: Verdana, Geneva, Arial, Helvetica, serif;
  13          color: #000000;
  14          background: #FFFFFF;
  15          width: 87%;
  16          margin: auto; }
  17
  18   div.section { width: 75%;
  19                 margin: auto; }
  20   div.section hr { margin: 4ex 0 1ex 0; }
  21   div.section h4 { background-color: #EEEEFF;
  22                    font-size: medium;
  23                    font-style: oblique;
  24                    font-weight: bold;
  25                    margin: 3ex 0 1.5ex 9%;
  26                    padding: 0.3ex 0 0.3ex 1%; }
  27   div.section p { margin: 1.5ex 0 1.5ex 10%; }
  28   div.section pre { margin: 3ex 0 3ex 9%;
  29                     background-color: #D6E8FF;
  30                     padding: 2ex 0 2ex 1%; }
  31   div.section table.fields { width: 90%;
  32                              margin: 1.5ex 0 1.5ex 10%; }
  33   div.section table.toc { width: 95%;
  34                           margin: 1.5ex 0 1.5ex 5%; }
  35   div.timestamp { text-align: center;
  36                   font-size: 69%;
  37                   margin: 1.5ex 0 1.5ex 0; }
  38
  39   h1 { text-align: center; }
  40   h3 { font-size: medium;
  41        margin: 4ex 0 1.5ex 0; }
  42
  43   p { text-align: justify; }
  44
  45   pre.colored { color: blue; }
  46
  47   span.keyword { font-family: monospace;
  48                  text-align: left;
  49                  white-space: pre;
  50                  color: darkblue; }
  51
  52   table.fields td.val { font-weight: bold;
  53                         text-align: right;
  54                         width: 30%;
  55                         vertical-align: baseline;
  56                         padding: 1ex 1em 1ex 0; }
  57   table.fields td.desc { vertical-align: baseline;
  58                          padding: 1ex 0 1ex 1em; }
  59   table.fields td.desc p:first-child { margin: 0; }
  60   table.fields td.desc p { margin: 1.5ex 0 0 0; }
  61   table.index { margin: 6ex auto 6ex auto;
  62                 border: 0;
  63                 border-collapse: separate;
  64                 border-spacing: 1em 0.3ex; }
  65   table.index tr { padding: 0; }
  66   table.index td { padding: 0; }
  67   table.index-toc-link { width: 100%;
  68                          border: 0;
  69                          border-spacing: 0;
  70                          margin: 1ex 0 1ex 0; }
  71   table.index-toc-link td.left { padding: 0 0.5em 0 0.5em;
  72                                  font-size: 83%;
  73                                  text-align: left; }
  74   table.index-toc-link td.middle { padding: 0 0.5em 0 0.5em;
  75                                    font-size: 83%;
  76                                    text-align: center; }
  77   table.index-toc-link td.right { padding: 0 0.5em 0 0.5em;
  78                                   font-size: 83%;
  79                                   text-align: right; }
  80   table.synopsis { margin: 6ex auto 6ex auto;
  81                    border: 0;
  82                    border-collapse: separate;
  83                    border-spacing: 2em 0.6ex; }
  84   table.synopsis tr { padding: 0; }
  85   table.synopsis td { padding: 0; }
  86   table.toc td.link { width: 30%;
  87                       text-align: right;
  88                       vertical-align: baseline;
  89                       padding: 1ex 1em 1ex 0; }
  90   table.toc td.desc { vertical-align: baseline;
  91                       padding: 1ex 0 1ex 1em;
  92                       text-align: left; }
  93   table.toc td.desc p:first-child { margin: 0;
  94                                     text-align: left; }
  95   table.toc td.desc p { margin: 1.5ex 0 0 0;
  96                         text-align: left; }
  97
  98 </style>
  99 </head>
 100 <body>
 101
 102 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table>
 103 <h1>FreeType-2.5.5 API Reference</h1>
 104
 105 <h1>System Interface</h1>
 106 <h2>Synopsis</h2>
 107 <table class="synopsis">
 108 <tr><td><a href="#FT_Memory">FT_Memory</a></td><td><a href="#FT_MemoryRec">FT_MemoryRec</a></td><td><a href="#FT_Stream_CloseFunc">FT_Stream_CloseFunc</a></td></tr>
 109 <tr><td><a href="#FT_Alloc_Func">FT_Alloc_Func</a></td><td><a href="#FT_Stream">FT_Stream</a></td><td><a href="#FT_StreamRec">FT_StreamRec</a></td></tr>
 110 <tr><td><a href="#FT_Free_Func">FT_Free_Func</a></td><td><a href="#FT_StreamDesc">FT_StreamDesc</a></td><td></td></tr>
 111 <tr><td><a href="#FT_Realloc_Func">FT_Realloc_Func</a></td><td><a href="#FT_Stream_IoFunc">FT_Stream_IoFunc</a></td><td></td></tr>
 112 </table>
 113
 114
 115 <p>This section contains various definitions related to memory management and i/o access. You need to understand this information if you want to use a custom memory manager or you own i/o streams.</p>
 116
 117 <div class="section">
 118 <h3 id="FT_Memory">FT_Memory</h3>
 119 <p>Defined in FT_SYSTEM_H (ftsystem.h).</p>
 120 <pre>
 121   <span class="keyword">typedef</span> <span class="keyword">struct</span> FT_MemoryRec_*  <b>FT_Memory</b>;
 122 </pre>
 123
 124 <p>A handle to a given memory manager object, defined with an <a href="ft2-system_interface.html#FT_MemoryRec">FT_MemoryRec</a> structure.</p>
 125
 126 <hr>
 127 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 128
 129 <div class="section">
 130 <h3 id="FT_Alloc_Func">FT_Alloc_Func</h3>
 131 <p>Defined in FT_SYSTEM_H (ftsystem.h).</p>
 132 <pre>
 133   <span class="keyword">typedef</span> <span class="keyword">void</span>*
 134   (*<b>FT_Alloc_Func</b>)( <a href="ft2-system_interface.html#FT_Memory">FT_Memory</a>  memory,
 135                     <span class="keyword">long</span>       size );
 136 </pre>
 137
 138 <p>A function used to allocate &lsquo;size&rsquo; bytes from &lsquo;memory&rsquo;.</p>
 139
 140 <h4>input</h4>
 141 <table class="fields">
 142 <tr><td class="val" id="memory">memory</td><td class="desc">
 143 <p>A handle to the source memory manager.</p>
 144 </td></tr>
 145 <tr><td class="val" id="size">size</td><td class="desc">
 146 <p>The size in bytes to allocate.</p>
 147 </td></tr>
 148 </table>
 149
 150 <h4>return</h4>
 151 <p>Address of new memory block. 0&nbsp;in case of failure.</p>
 152
 153 <hr>
 154 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 155
 156 <div class="section">
 157 <h3 id="FT_Free_Func">FT_Free_Func</h3>
 158 <p>Defined in FT_SYSTEM_H (ftsystem.h).</p>
 159 <pre>
 160   <span class="keyword">typedef</span> <span class="keyword">void</span>
 161   (*<b>FT_Free_Func</b>)( <a href="ft2-system_interface.html#FT_Memory">FT_Memory</a>  memory,
 162                    <span class="keyword">void</span>*      block );
 163 </pre>
 164
 165 <p>A function used to release a given block of memory.</p>
 166
 167 <h4>input</h4>
 168 <table class="fields">
 169 <tr><td class="val" id="memory">memory</td><td class="desc">
 170 <p>A handle to the source memory manager.</p>
 171 </td></tr>
 172 <tr><td class="val" id="block">block</td><td class="desc">
 173 <p>The address of the target memory block.</p>
 174 </td></tr>
 175 </table>
 176
 177 <hr>
 178 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 179
 180 <div class="section">
 181 <h3 id="FT_Realloc_Func">FT_Realloc_Func</h3>
 182 <p>Defined in FT_SYSTEM_H (ftsystem.h).</p>
 183 <pre>
 184   <span class="keyword">typedef</span> <span class="keyword">void</span>*
 185   (*<b>FT_Realloc_Func</b>)( <a href="ft2-system_interface.html#FT_Memory">FT_Memory</a>  memory,
 186                       <span class="keyword">long</span>       cur_size,
 187                       <span class="keyword">long</span>       new_size,
 188                       <span class="keyword">void</span>*      block );
 189 </pre>
 190
 191 <p>A function used to re-allocate a given block of memory.</p>
 192
 193 <h4>input</h4>
 194 <table class="fields">
 195 <tr><td class="val" id="memory">memory</td><td class="desc">
 196 <p>A handle to the source memory manager.</p>
 197 </td></tr>
 198 <tr><td class="val" id="cur_size">cur_size</td><td class="desc">
 199 <p>The block's current size in bytes.</p>
 200 </td></tr>
 201 <tr><td class="val" id="new_size">new_size</td><td class="desc">
 202 <p>The block's requested new size.</p>
 203 </td></tr>
 204 <tr><td class="val" id="block">block</td><td class="desc">
 205 <p>The block's current address.</p>
 206 </td></tr>
 207 </table>
 208
 209 <h4>return</h4>
 210 <p>New block address. 0&nbsp;in case of memory shortage.</p>
 211
 212 <h4>note</h4>
 213 <p>In case of error, the old block must still be available.</p>
 214
 215 <hr>
 216 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 217
 218 <div class="section">
 219 <h3 id="FT_MemoryRec">FT_MemoryRec</h3>
 220 <p>Defined in FT_SYSTEM_H (ftsystem.h).</p>
 221 <pre>
 222   <span class="keyword">struct</span>  FT_MemoryRec_
 223   {
 224     <span class="keyword">void</span>*            user;
 225     <a href="ft2-system_interface.html#FT_Alloc_Func">FT_Alloc_Func</a>    alloc;
 226     <a href="ft2-system_interface.html#FT_Free_Func">FT_Free_Func</a>     free;
 227     <a href="ft2-system_interface.html#FT_Realloc_Func">FT_Realloc_Func</a>  realloc;
 228   };
 229 </pre>
 230
 231 <p>A structure used to describe a given memory manager to FreeType&nbsp;2.</p>
 232
 233 <h4>fields</h4>
 234 <table class="fields">
 235 <tr><td class="val" id="user">user</td><td class="desc">
 236 <p>A generic typeless pointer for user data.</p>
 237 </td></tr>
 238 <tr><td class="val" id="alloc">alloc</td><td class="desc">
 239 <p>A pointer type to an allocation function.</p>
 240 </td></tr>
 241 <tr><td class="val" id="free">free</td><td class="desc">
 242 <p>A pointer type to an memory freeing function.</p>
 243 </td></tr>
 244 <tr><td class="val" id="realloc">realloc</td><td class="desc">
 245 <p>A pointer type to a reallocation function.</p>
 246 </td></tr>
 247 </table>
 248
 249 <hr>
 250 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 251
 252 <div class="section">
 253 <h3 id="FT_Stream">FT_Stream</h3>
 254 <p>Defined in FT_SYSTEM_H (ftsystem.h).</p>
 255 <pre>
 256   <span class="keyword">typedef</span> <span class="keyword">struct</span> FT_StreamRec_*  <b>FT_Stream</b>;
 257 </pre>
 258
 259 <p>A handle to an input stream.</p>
 260
 261 <h4>also</h4>
 262 <p>See <a href="ft2-system_interface.html#FT_StreamRec">FT_StreamRec</a> for the publicly accessible fields of a given stream object.</p>
 263
 264 <hr>
 265 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 266
 267 <div class="section">
 268 <h3 id="FT_StreamDesc">FT_StreamDesc</h3>
 269 <p>Defined in FT_SYSTEM_H (ftsystem.h).</p>
 270 <pre>
 271   <span class="keyword">typedef</span> <span class="keyword">union</span>  FT_StreamDesc_
 272   {
 273     <span class="keyword">long</span>   value;
 274     <span class="keyword">void</span>*  pointer;
 275
 276   } <b>FT_StreamDesc</b>;
 277 </pre>
 278
 279 <p>A union type used to store either a long or a pointer. This is used to store a file descriptor or a &lsquo;FILE*&rsquo; in an input stream.</p>
 280
 281 <hr>
 282 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 283
 284 <div class="section">
 285 <h3 id="FT_Stream_IoFunc">FT_Stream_IoFunc</h3>
 286 <p>Defined in FT_SYSTEM_H (ftsystem.h).</p>
 287 <pre>
 288   <span class="keyword">typedef</span> <span class="keyword">unsigned</span> <span class="keyword">long</span>
 289   (*<b>FT_Stream_IoFunc</b>)( <a href="ft2-system_interface.html#FT_Stream">FT_Stream</a>       stream,
 290                        <span class="keyword">unsigned</span> <span class="keyword">long</span>   offset,
 291                        <span class="keyword">unsigned</span> <span class="keyword">char</span>*  buffer,
 292                        <span class="keyword">unsigned</span> <span class="keyword">long</span>   count );
 293 </pre>
 294
 295 <p>A function used to seek and read data from a given input stream.</p>
 296
 297 <h4>input</h4>
 298 <table class="fields">
 299 <tr><td class="val" id="stream">stream</td><td class="desc">
 300 <p>A handle to the source stream.</p>
 301 </td></tr>
 302 <tr><td class="val" id="offset">offset</td><td class="desc">
 303 <p>The offset of read in stream (always from start).</p>
 304 </td></tr>
 305 <tr><td class="val" id="buffer">buffer</td><td class="desc">
 306 <p>The address of the read buffer.</p>
 307 </td></tr>
 308 <tr><td class="val" id="count">count</td><td class="desc">
 309 <p>The number of bytes to read from the stream.</p>
 310 </td></tr>
 311 </table>
 312
 313 <h4>return</h4>
 314 <p>The number of bytes effectively read by the stream.</p>
 315
 316 <h4>note</h4>
 317 <p>This function might be called to perform a seek or skip operation with a &lsquo;count&rsquo; of&nbsp;0. A non-zero return value then indicates an error.</p>
 318
 319 <hr>
 320 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 321
 322 <div class="section">
 323 <h3 id="FT_Stream_CloseFunc">FT_Stream_CloseFunc</h3>
 324 <p>Defined in FT_SYSTEM_H (ftsystem.h).</p>
 325 <pre>
 326   <span class="keyword">typedef</span> <span class="keyword">void</span>
 327   (*<b>FT_Stream_CloseFunc</b>)( <a href="ft2-system_interface.html#FT_Stream">FT_Stream</a>  stream );
 328 </pre>
 329
 330 <p>A function used to close a given input stream.</p>
 331
 332 <h4>input</h4>
 333 <table class="fields">
 334 <tr><td class="val" id="stream">stream</td><td class="desc">
 335 <p>A handle to the target stream.</p>
 336 </td></tr>
 337 </table>
 338
 339 <hr>
 340 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 341
 342 <div class="section">
 343 <h3 id="FT_StreamRec">FT_StreamRec</h3>
 344 <p>Defined in FT_SYSTEM_H (ftsystem.h).</p>
 345 <pre>
 346   <span class="keyword">typedef</span> <span class="keyword">struct</span>  FT_StreamRec_
 347   {
 348     <span class="keyword">unsigned</span> <span class="keyword">char</span>*       base;
 349     <span class="keyword">unsigned</span> <span class="keyword">long</span>        size;
 350     <span class="keyword">unsigned</span> <span class="keyword">long</span>        pos;
 351
 352     <a href="ft2-system_interface.html#FT_StreamDesc">FT_StreamDesc</a>        descriptor;
 353     <a href="ft2-system_interface.html#FT_StreamDesc">FT_StreamDesc</a>        pathname;
 354     <a href="ft2-system_interface.html#FT_Stream_IoFunc">FT_Stream_IoFunc</a>     read;
 355     <a href="ft2-system_interface.html#FT_Stream_CloseFunc">FT_Stream_CloseFunc</a>  close;
 356
 357     <a href="ft2-system_interface.html#FT_Memory">FT_Memory</a>            memory;
 358     <span class="keyword">unsigned</span> <span class="keyword">char</span>*       cursor;
 359     <span class="keyword">unsigned</span> <span class="keyword">char</span>*       limit;
 360
 361   } <b>FT_StreamRec</b>;
 362 </pre>
 363
 364 <p>A structure used to describe an input stream.</p>
 365
 366 <h4>input</h4>
 367 <table class="fields">
 368 <tr><td class="val" id="base">base</td><td class="desc">
 369 <p>For memory-based streams, this is the address of the first stream byte in memory. This field should always be set to NULL for disk-based streams.</p>
 370 </td></tr>
 371 <tr><td class="val" id="size">size</td><td class="desc">
 372 <p>The stream size in bytes.</p>
 373 <p>In case of compressed streams where the size is unknown before actually doing the decompression, the value is set to 0x7FFFFFFF. (Note that this size value can occur for normal streams also; it is thus just a hint.)</p>
 374 </td></tr>
 375 <tr><td class="val" id="pos">pos</td><td class="desc">
 376 <p>The current position within the stream.</p>
 377 </td></tr>
 378 <tr><td class="val" id="descriptor">descriptor</td><td class="desc">
 379 <p>This field is a union that can hold an integer or a pointer. It is used by stream implementations to store file descriptors or &lsquo;FILE*&rsquo; pointers.</p>
 380 </td></tr>
 381 <tr><td class="val" id="pathname">pathname</td><td class="desc">
 382 <p>This field is completely ignored by FreeType. However, it is often useful during debugging to use it to store the stream's filename (where available).</p>
 383 </td></tr>
 384 <tr><td class="val" id="read">read</td><td class="desc">
 385 <p>The stream's input function.</p>
 386 </td></tr>
 387 <tr><td class="val" id="close">close</td><td class="desc">
 388 <p>The stream's close function.</p>
 389 </td></tr>
 390 <tr><td class="val" id="memory">memory</td><td class="desc">
 391 <p>The memory manager to use to preload frames. This is set internally by FreeType and shouldn't be touched by stream implementations.</p>
 392 </td></tr>
 393 <tr><td class="val" id="cursor">cursor</td><td class="desc">
 394 <p>This field is set and used internally by FreeType when parsing frames.</p>
 395 </td></tr>
 396 <tr><td class="val" id="limit">limit</td><td class="desc">
 397 <p>This field is set and used internally by FreeType when parsing frames.</p>
 398 </td></tr>
 399 </table>
 400
 401 <hr>
 402 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 403
 404 </body>
 405 </html>