libraries/freetype-2.0.5/include/freetype/ftsystem.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftsystem.h                                                             */
   4 /*                                                                         */
   5 /*    FreeType low-level system interface definition (specification).      */
   6 /*                                                                         */
   7 /*  Copyright 1996-2001 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   /* <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        */
  41   /*    management and i/o access.  You need to understand this            */
  42   /*    information if you want to use a custom memory manager or you own  */
  43   /*    input i/o streams.                                                 */
  44   /*                                                                       */
  45   /*************************************************************************/
  46
  47
  48   /*************************************************************************/
  49   /*                                                                       */
  50   /*                  M E M O R Y   M A N A G E M E N T                    */
  51   /*                                                                       */
  52   /*************************************************************************/
  53
  54
  55   /*************************************************************************/
  56   /*                                                                       */
  57   /* @type:                                                                */
  58   /*    FT_Memory                                                          */
  59   /*                                                                       */
  60   /* @description:                                                         */
  61   /*    A handle to a given memory manager object, defined with a          */
  62   /*    @FT_MemoryRec structure.                                           */
  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 :: A handle to the source memory manager.                   */
  77   /*                                                                       */
  78   /*    size   :: The size in bytes to allocate.                           */
  79   /*                                                                       */
  80   /* @return:                                                              */
  81   /*    Address of new memory block.  0 in case of failure.                */
  82   /*                                                                       */
  83   typedef void*
  84   (*FT_Alloc_Func)( FT_Memory  memory,
  85                     long       size );
  86
  87
  88   /*************************************************************************/
  89   /*                                                                       */
  90   /* @functype:                                                            */
  91   /*    FT_Free_Func                                                       */
  92   /*                                                                       */
  93   /* @description:                                                         */
  94   /*    A function used to release a given block of memory.                */
  95   /*                                                                       */
  96   /* @input:                                                               */
  97   /*    memory :: A handle to the source memory manager.                   */
  98   /*                                                                       */
  99   /*    block  :: The address of the target memory block.                  */
 100   /*                                                                       */
 101   typedef void
 102   (*FT_Free_Func)( FT_Memory  memory,
 103                    void*      block );
 104
 105
 106   /*************************************************************************/
 107   /*                                                                       */
 108   /* @functype:                                                            */
 109   /*    FT_Realloc_Func                                                    */
 110   /*                                                                       */
 111   /* @description:                                                         */
 112   /*    a function used to re-allocate a given block of memory.            */
 113   /*                                                                       */
 114   /* @input:                                                               */
 115   /*    memory   :: A handle to the source memory manager.                 */
 116   /*                                                                       */
 117   /*    cur_size :: The block's current size in bytes.                     */
 118   /*                                                                       */
 119   /*    new_size :: The block's requested new size.                        */
 120   /*                                                                       */
 121   /*    block    :: The block's current address.                           */
 122   /*                                                                       */
 123   /* @return:                                                              */
 124   /*    New block address.  0 in case of memory shortage.                  */
 125   /*                                                                       */
 126   /* @note:                                                                */
 127   /*   In case of error, the old block must still be available.            */
 128   /*                                                                       */
 129   typedef void*
 130   (*FT_Realloc_Func)( FT_Memory  memory,
 131                       long       cur_size,
 132                       long       new_size,
 133                       void*      block );
 134
 135
 136   /*************************************************************************/
 137   /*                                                                       */
 138   /* @struct:                                                              */
 139   /*    FT_MemoryRec                                                       */
 140   /*                                                                       */
 141   /* @description:                                                         */
 142   /*    A structure used to describe a given memory manager to FreeType 2. */
 143   /*                                                                       */
 144   /* @fields:                                                              */
 145   /*    user    :: A generic typeless pointer for user data.               */
 146   /*                                                                       */
 147   /*    alloc   :: A pointer type to an allocation function.               */
 148   /*                                                                       */
 149   /*    free    :: A pointer type to an memory freeing function.           */
 150   /*                                                                       */
 151   /*    realloc :: A pointer type to a reallocation function.              */
 152   /*                                                                       */
 153   struct  FT_MemoryRec_
 154   {
 155     void*            user;
 156     FT_Alloc_Func    alloc;
 157     FT_Free_Func     free;
 158     FT_Realloc_Func  realloc;
 159   };
 160
 161
 162   /*************************************************************************/
 163   /*                                                                       */
 164   /*                       I / O   M A N A G E M E N T                     */
 165   /*                                                                       */
 166   /*************************************************************************/
 167
 168
 169   /*************************************************************************/
 170   /*                                                                       */
 171   /* @type:                                                                */
 172   /*    FT_Stream                                                          */
 173   /*                                                                       */
 174   /* @description:                                                         */
 175   /*    A handle to an input stream.                                       */
 176   /*                                                                       */
 177   typedef struct FT_StreamRec_*  FT_Stream;
 178
 179
 180   /*************************************************************************/
 181   /*                                                                       */
 182   /* @struct:                                                              */
 183   /*    FT_StreamDesc                                                      */
 184   /*                                                                       */
 185   /* @description:                                                         */
 186   /*    A union type used to store either a long or a pointer.  This is    */
 187   /*    used to store a file descriptor or a FILE* in an input stream.     */
 188   /*                                                                       */
 189   typedef union  FT_StreamDesc_
 190   {
 191     long   value;
 192     void*  pointer;
 193
 194   } FT_StreamDesc;
 195
 196
 197   /*************************************************************************/
 198   /*                                                                       */
 199   /* @functype:                                                            */
 200   /*    FT_Stream_IO                                                       */
 201   /*                                                                       */
 202   /* @description:                                                         */
 203   /*    A function used to seek and read data from a given input stream.   */
 204   /*                                                                       */
 205   /* @input:                                                               */
 206   /*    stream :: A handle to the source stream.                           */
 207   /*                                                                       */
 208   /*    offset :: The offset of read in stream (always from start).        */
 209   /*                                                                       */
 210   /*    buffer :: The address of the read buffer.                          */
 211   /*                                                                       */
 212   /*    count  :: The number of bytes to read from the stream.             */
 213   /*                                                                       */
 214   /* @return:                                                              */
 215   /*    The number of bytes effectively read by the stream.                */
 216   /*                                                                       */
 217   /* @note:                                                                */
 218   /*    This function might be called to perform a seek or skip operation  */
 219   /*    with a `count' of 0.                                               */
 220   /*                                                                       */
 221   typedef unsigned long
 222   (*FT_Stream_IO)( FT_Stream       stream,
 223                    unsigned long   offset,
 224                    unsigned char*  buffer,
 225                    unsigned long   count );
 226
 227
 228   /*************************************************************************/
 229   /*                                                                       */
 230   /* @functype:                                                            */
 231   /*    FT_Stream_Close                                                    */
 232   /*                                                                       */
 233   /* @description:                                                         */
 234   /*    A function used to close a given input stream.                     */
 235   /*                                                                       */
 236   /* @input:                                                               */
 237   /*   stream :: A handle to the target stream.                            */
 238   /*                                                                       */
 239   typedef void
 240   (*FT_Stream_Close)( FT_Stream  stream );
 241
 242
 243   /*************************************************************************/
 244   /*                                                                       */
 245   /* @struct:                                                              */
 246   /*    FT_StreamRec                                                       */
 247   /*                                                                       */
 248   /* @description:                                                         */
 249   /*   A structure used to describe an input stream.                       */
 250   /*                                                                       */
 251   /* @input:                                                               */
 252   /*   base       :: For memory-based streams, this is the address of the  */
 253   /*                 first stream byte in memory.  This field should       */
 254   /*                 always be set to NULL for disk-based streams.         */
 255   /*                                                                       */
 256   /*   size       :: The stream size in bytes.                             */
 257   /*                                                                       */
 258   /*   pos        :: The current position within the stream.               */
 259   /*                                                                       */
 260   /*   descriptor :: This field is a union that can hold an integer or a   */
 261   /*                 pointer.  It is used by stream implementations to     */
 262   /*                 store file descriptors or FILE* pointers.             */
 263   /*                                                                       */
 264   /*   pathname   :: This field is completely ignored by FreeType.         */
 265   /*                 However, it is often useful during debugging to use   */
 266   /*                 it to store the stream's filename (where available).  */
 267   /*                                                                       */
 268   /*   read       :: The stream's input function.                          */
 269   /*                                                                       */
 270   /*   close      :: The stream;s close function.                          */
 271   /*                                                                       */
 272   /*   memory     :: The memory manager to use to preload frames.  This is */
 273   /*                 set internally by FreeType and shouldn't be touched   */
 274   /*                 by stream implementations.                            */
 275   /*                                                                       */
 276   /*   cursor     :: This field is set and used internally by FreeType     */
 277   /*                 when parsing frames.                                  */
 278   /*                                                                       */
 279   /*   limit      :: This field is set and used internally by FreeType     */
 280   /*                 when parsing frames.                                  */
 281   /*                                                                       */
 282   struct  FT_StreamRec_
 283   {
 284     unsigned char*   base;
 285     unsigned long    size;
 286     unsigned long    pos;
 287
 288     FT_StreamDesc    descriptor;
 289     FT_StreamDesc    pathname;
 290     FT_Stream_IO     read;
 291     FT_Stream_Close  close;
 292
 293     FT_Memory        memory;
 294     unsigned char*   cursor;
 295     unsigned char*   limit;
 296   };
 297
 298
 299   /* */
 300
 301
 302 FT_END_HEADER
 303
 304 #endif /* __FTSYSTEM_H__ */
 305
 306
 307 /* END */