lib/freetype/include/freetype/ftsystem.h

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