include/ftsystem.h

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