thirdparty/freetype-2.3.12/include/freetype/ftsystem.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftsystem.h                                                             */
   4 /*                                                                         */
   5 /*    FreeType low-level system interface definition (specification).      */
   6 /*                                                                         */
   7 /*  Copyright 1996-2001, 2002, 2005 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    */
 196   typedef struct FT_StreamRec_*  FT_Stream;
 197
 198
 199   /*************************************************************************
 200    *
 201    * @struct:
 202    *   FT_StreamDesc
 203    *
 204    * @description:
 205    *   A union type used to store either a long or a pointer.  This is used
 206    *   to store a file descriptor or a `FILE*' in an input stream.
 207    *
 208    */
 209   typedef union  FT_StreamDesc_
 210   {
 211     long   value;
 212     void*  pointer;
 213
 214   } FT_StreamDesc;
 215
 216
 217   /*************************************************************************
 218    *
 219    * @functype:
 220    *   FT_Stream_IoFunc
 221    *
 222    * @description:
 223    *   A function used to seek and read data from a given input stream.
 224    *
 225    * @input:
 226    *   stream ::
 227    *     A handle to the source stream.
 228    *
 229    *   offset ::
 230    *     The offset of read in stream (always from start).
 231    *
 232    *   buffer ::
 233    *     The address of the read buffer.
 234    *
 235    *   count ::
 236    *     The number of bytes to read from the stream.
 237    *
 238    * @return:
 239    *   The number of bytes effectively read by the stream.
 240    *
 241    * @note:
 242    *   This function might be called to perform a seek or skip operation
 243    *   with a `count' of~0.
 244    *
 245    */
 246   typedef unsigned long
 247   (*FT_Stream_IoFunc)( FT_Stream       stream,
 248                        unsigned long   offset,
 249                        unsigned char*  buffer,
 250                        unsigned long   count );
 251
 252
 253   /*************************************************************************
 254    *
 255    * @functype:
 256    *   FT_Stream_CloseFunc
 257    *
 258    * @description:
 259    *   A function used to close a given input stream.
 260    *
 261    * @input:
 262    *  stream ::
 263    *     A handle to the target stream.
 264    *
 265    */
 266   typedef void
 267   (*FT_Stream_CloseFunc)( FT_Stream  stream );
 268
 269
 270   /*************************************************************************
 271    *
 272    * @struct:
 273    *   FT_StreamRec
 274    *
 275    * @description:
 276    *   A structure used to describe an input stream.
 277    *
 278    * @input:
 279    *   base ::
 280    *     For memory-based streams, this is the address of the first stream
 281    *     byte in memory.  This field should always be set to NULL for
 282    *     disk-based streams.
 283    *
 284    *   size ::
 285    *     The stream size in bytes.
 286    *
 287    *   pos ::
 288    *     The current position within the stream.
 289    *
 290    *   descriptor ::
 291    *     This field is a union that can hold an integer or a pointer.  It is
 292    *     used by stream implementations to store file descriptors or `FILE*'
 293    *     pointers.
 294    *
 295    *   pathname ::
 296    *     This field is completely ignored by FreeType.  However, it is often
 297    *     useful during debugging to use it to store the stream's filename
 298    *     (where available).
 299    *
 300    *   read ::
 301    *     The stream's input function.
 302    *
 303    *   close ::
 304    *     The stream;s close function.
 305    *
 306    *   memory ::
 307    *     The memory manager to use to preload frames.  This is set
 308    *     internally by FreeType and shouldn't be touched by stream
 309    *     implementations.
 310    *
 311    *   cursor ::
 312    *     This field is set and used internally by FreeType when parsing
 313    *     frames.
 314    *
 315    *   limit ::
 316    *     This field is set and used internally by FreeType when parsing
 317    *     frames.
 318    *
 319    */
 320   typedef struct  FT_StreamRec_
 321   {
 322     unsigned char*       base;
 323     unsigned long        size;
 324     unsigned long        pos;
 325
 326     FT_StreamDesc        descriptor;
 327     FT_StreamDesc        pathname;
 328     FT_Stream_IoFunc     read;
 329     FT_Stream_CloseFunc  close;
 330
 331     FT_Memory            memory;
 332     unsigned char*       cursor;
 333     unsigned char*       limit;
 334
 335   } FT_StreamRec;
 336
 337
 338   /* */
 339
 340
 341 FT_END_HEADER
 342
 343 #endif /* __FTSYSTEM_H__ */
 344
 345
 346 /* END */