include/freetype/ftsystem.h

   1 /****************************************************************************
   2  *
   3  * ftsystem.h
   4  *
   5  *   FreeType low-level system interface definition (specification).
   6  *
   7  * Copyright (C) 1996-2020 by
   8  * David Turner, Robert Wilhelm, and Werner Lemberg.
   9  *
  10  * This file is part of the FreeType project, and may only be used,
  11  * modified, and distributed under the terms of the FreeType project
  12  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
  13  * this file you indicate that you have read the license and
  14  * understand and accept it fully.
  15  *
  16  */
  17
  18
  19 #ifndef FTSYSTEM_H_
  20 #define FTSYSTEM_H_
  21
  22
  23
  24
  25 FT_BEGIN_HEADER
  26
  27
  28   /**************************************************************************
  29    *
  30    * @section:
  31    *  system_interface
  32    *
  33    * @title:
  34    *  System Interface
  35    *
  36    * @abstract:
  37    *  How FreeType manages memory and i/o.
  38    *
  39    * @description:
  40    *  This section contains various definitions related to memory management
  41    *  and i/o access.  You need to understand this information if you want to
  42    *  use a custom memory manager or you own i/o streams.
  43    *
  44    */
  45
  46
  47   /**************************************************************************
  48    *
  49    *                 M E M O R Y   M A N A G E M E N T
  50    *
  51    */
  52
  53
  54   /**************************************************************************
  55    *
  56    * @type:
  57    *   FT_Memory
  58    *
  59    * @description:
  60    *   A handle to a given memory manager object, defined with an
  61    *   @FT_MemoryRec structure.
  62    *
  63    */
  64   typedef struct FT_MemoryRec_*  FT_Memory;
  65
  66
  67   /**************************************************************************
  68    *
  69    * @functype:
  70    *   FT_Alloc_Func
  71    *
  72    * @description:
  73    *   A function used to allocate `size` bytes from `memory`.
  74    *
  75    * @input:
  76    *   memory ::
  77    *     A handle to the source memory manager.
  78    *
  79    *   size ::
  80    *     The size in bytes to allocate.
  81    *
  82    * @return:
  83    *   Address of new memory block.  0~in case of failure.
  84    *
  85    */
  86   typedef void*
  87   (*FT_Alloc_Func)( FT_Memory  memory,
  88                     long       size );
  89
  90
  91   /**************************************************************************
  92    *
  93    * @functype:
  94    *   FT_Free_Func
  95    *
  96    * @description:
  97    *   A function used to release a given block of memory.
  98    *
  99    * @input:
 100    *   memory ::
 101    *     A handle to the source memory manager.
 102    *
 103    *   block ::
 104    *     The address of the target memory block.
 105    *
 106    */
 107   typedef void
 108   (*FT_Free_Func)( FT_Memory  memory,
 109                    void*      block );
 110
 111
 112   /**************************************************************************
 113    *
 114    * @functype:
 115    *   FT_Realloc_Func
 116    *
 117    * @description:
 118    *   A function used to re-allocate a given block of memory.
 119    *
 120    * @input:
 121    *   memory ::
 122    *     A handle to the source memory manager.
 123    *
 124    *   cur_size ::
 125    *     The block's current size in bytes.
 126    *
 127    *   new_size ::
 128    *     The block's requested new size.
 129    *
 130    *   block ::
 131    *     The block's current address.
 132    *
 133    * @return:
 134    *   New block address.  0~in case of memory shortage.
 135    *
 136    * @note:
 137    *   In case of error, the old block must still be available.
 138    *
 139    */
 140   typedef void*
 141   (*FT_Realloc_Func)( FT_Memory  memory,
 142                       long       cur_size,
 143                       long       new_size,
 144                       void*      block );
 145
 146
 147   /**************************************************************************
 148    *
 149    * @struct:
 150    *   FT_MemoryRec
 151    *
 152    * @description:
 153    *   A structure used to describe a given memory manager to FreeType~2.
 154    *
 155    * @fields:
 156    *   user ::
 157    *     A generic typeless pointer for user data.
 158    *
 159    *   alloc ::
 160    *     A pointer type to an allocation function.
 161    *
 162    *   free ::
 163    *     A pointer type to an memory freeing function.
 164    *
 165    *   realloc ::
 166    *     A pointer type to a reallocation function.
 167    *
 168    */
 169   struct  FT_MemoryRec_
 170   {
 171     void*            user;
 172     FT_Alloc_Func    alloc;
 173     FT_Free_Func     free;
 174     FT_Realloc_Func  realloc;
 175   };
 176
 177
 178   /**************************************************************************
 179    *
 180    *                      I / O   M A N A G E M E N T
 181    *
 182    */
 183
 184
 185   /**************************************************************************
 186    *
 187    * @type:
 188    *   FT_Stream
 189    *
 190    * @description:
 191    *   A handle to an input stream.
 192    *
 193    * @also:
 194    *   See @FT_StreamRec for the publicly accessible fields of a given stream
 195    *   object.
 196    *
 197    */
 198   typedef struct FT_StreamRec_*  FT_Stream;
 199
 200
 201   /**************************************************************************
 202    *
 203    * @struct:
 204    *   FT_StreamDesc
 205    *
 206    * @description:
 207    *   A union type used to store either a long or a pointer.  This is used
 208    *   to store a file descriptor or a `FILE*` in an input stream.
 209    *
 210    */
 211   typedef union  FT_StreamDesc_
 212   {
 213     long   value;
 214     void*  pointer;
 215
 216   } FT_StreamDesc;
 217
 218
 219   /**************************************************************************
 220    *
 221    * @functype:
 222    *   FT_Stream_IoFunc
 223    *
 224    * @description:
 225    *   A function used to seek and read data from a given input stream.
 226    *
 227    * @input:
 228    *   stream ::
 229    *     A handle to the source stream.
 230    *
 231    *   offset ::
 232    *     The offset of read in stream (always from start).
 233    *
 234    *   buffer ::
 235    *     The address of the read buffer.
 236    *
 237    *   count ::
 238    *     The number of bytes to read from the stream.
 239    *
 240    * @return:
 241    *   The number of bytes effectively read by the stream.
 242    *
 243    * @note:
 244    *   This function might be called to perform a seek or skip operation with
 245    *   a `count` of~0.  A non-zero return value then indicates an error.
 246    *
 247    */
 248   typedef unsigned long
 249   (*FT_Stream_IoFunc)( FT_Stream       stream,
 250                        unsigned long   offset,
 251                        unsigned char*  buffer,
 252                        unsigned long   count );
 253
 254
 255   /**************************************************************************
 256    *
 257    * @functype:
 258    *   FT_Stream_CloseFunc
 259    *
 260    * @description:
 261    *   A function used to close a given input stream.
 262    *
 263    * @input:
 264    *  stream ::
 265    *    A handle to the target stream.
 266    *
 267    */
 268   typedef void
 269   (*FT_Stream_CloseFunc)( FT_Stream  stream );
 270
 271
 272   /**************************************************************************
 273    *
 274    * @struct:
 275    *   FT_StreamRec
 276    *
 277    * @description:
 278    *   A structure used to describe an input stream.
 279    *
 280    * @input:
 281    *   base ::
 282    *     For memory-based streams, this is the address of the first stream
 283    *     byte in memory.  This field should always be set to `NULL` for
 284    *     disk-based streams.
 285    *
 286    *   size ::
 287    *     The stream size in bytes.
 288    *
 289    *     In case of compressed streams where the size is unknown before
 290    *     actually doing the decompression, the value is set to 0x7FFFFFFF.
 291    *     (Note that this size value can occur for normal streams also; it is
 292    *     thus just a hint.)
 293    *
 294    *   pos ::
 295    *     The current position within the stream.
 296    *
 297    *   descriptor ::
 298    *     This field is a union that can hold an integer or a pointer.  It is
 299    *     used by stream implementations to store file descriptors or `FILE*`
 300    *     pointers.
 301    *
 302    *   pathname ::
 303    *     This field is completely ignored by FreeType.  However, it is often
 304    *     useful during debugging to use it to store the stream's filename
 305    *     (where available).
 306    *
 307    *   read ::
 308    *     The stream's input function.
 309    *
 310    *   close ::
 311    *     The stream's close function.
 312    *
 313    *   memory ::
 314    *     The memory manager to use to preload frames.  This is set internally
 315    *     by FreeType and shouldn't be touched by stream implementations.
 316    *
 317    *   cursor ::
 318    *     This field is set and used internally by FreeType when parsing
 319    *     frames.  In particular, the `FT_GET_XXX` macros use this instead of
 320    *     the `pos` field.
 321    *
 322    *   limit ::
 323    *     This field is set and used internally by FreeType when parsing
 324    *     frames.
 325    *
 326    */
 327   typedef struct  FT_StreamRec_
 328   {
 329     unsigned char*       base;
 330     unsigned long        size;
 331     unsigned long        pos;
 332
 333     FT_StreamDesc        descriptor;
 334     FT_StreamDesc        pathname;
 335     FT_Stream_IoFunc     read;
 336     FT_Stream_CloseFunc  close;
 337
 338     FT_Memory            memory;
 339     unsigned char*       cursor;
 340     unsigned char*       limit;
 341
 342   } FT_StreamRec;
 343
 344   /* */
 345
 346
 347 FT_END_HEADER
 348
 349 #endif /* FTSYSTEM_H_ */
 350
 351
 352 /* END */