lib/freetype/include/freetype/internal/ftmemory.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftmemory.h                                                             */
   4 /*                                                                         */
   5 /*    The FreeType memory management macros (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 __FTMEMORY_H__
  20 #define __FTMEMORY_H__
  21
  22
  23 #include <ft2build.h>
  24 #include FT_CONFIG_CONFIG_H
  25 #include FT_TYPES_H
  26
  27
  28 FT_BEGIN_HEADER
  29
  30
  31   /*************************************************************************/
  32   /*                                                                       */
  33   /* <Macro>                                                               */
  34   /*    FT_SET_ERROR                                                       */
  35   /*                                                                       */
  36   /* <Description>                                                         */
  37   /*    This macro is used to set an implicit `error' variable to a given  */
  38   /*    expression's value (usually a function call), and convert it to a  */
  39   /*    boolean which is set whenever the value is != 0.                   */
  40   /*                                                                       */
  41 #undef  FT_SET_ERROR
  42 #define FT_SET_ERROR( expression ) \
  43           ( ( error = (expression) ) != 0 )
  44
  45
  46   /*************************************************************************/
  47   /*************************************************************************/
  48   /*************************************************************************/
  49   /****                                                                 ****/
  50   /****                                                                 ****/
  51   /****                           M E M O R Y                           ****/
  52   /****                                                                 ****/
  53   /****                                                                 ****/
  54   /*************************************************************************/
  55   /*************************************************************************/
  56   /*************************************************************************/
  57
  58 #ifdef FT_DEBUG_MEMORY
  59
  60   FT_BASE( FT_Error )
  61   FT_Alloc_Debug( FT_Memory    memory,
  62                   FT_Long      size,
  63                   void*       *P,
  64                   const char*  file_name,
  65                   FT_Long      line_no );
  66
  67   FT_BASE( FT_Error )
  68   FT_Realloc_Debug( FT_Memory    memory,
  69                     FT_Long      current,
  70                     FT_Long      size,
  71                     void*       *P,
  72                     const char*  file_name,
  73                     FT_Long      line_no );
  74
  75   FT_BASE( void )
  76   FT_Free_Debug( FT_Memory    memory,
  77                  FT_Pointer   block,
  78                  const char*  file_name,
  79                  FT_Long      line_no );
  80
  81 #endif
  82
  83
  84   /*************************************************************************/
  85   /*                                                                       */
  86   /* <Function>                                                            */
  87   /*    FT_Alloc                                                           */
  88   /*                                                                       */
  89   /* <Description>                                                         */
  90   /*    Allocates a new block of memory.  The returned area is always      */
  91   /*    zero-filled; this is a strong convention in many FreeType parts.   */
  92   /*                                                                       */
  93   /* <Input>                                                               */
  94   /*    memory :: A handle to a given `memory object' which handles        */
  95   /*              allocation.                                              */
  96   /*                                                                       */
  97   /*    size   :: The size in bytes of the block to allocate.              */
  98   /*                                                                       */
  99   /* <Output>                                                              */
 100   /*    P      :: A pointer to the fresh new block.  It should be set to   */
 101   /*              NULL if `size' is 0, or in case of error.                */
 102   /*                                                                       */
 103   /* <Return>                                                              */
 104   /*    FreeType error code.  0 means success.                             */
 105   /*                                                                       */
 106   FT_BASE( FT_Error )
 107   FT_Alloc( FT_Memory  memory,
 108             FT_Long    size,
 109             void*     *P );
 110
 111
 112   /*************************************************************************/
 113   /*                                                                       */
 114   /* <Function>                                                            */
 115   /*    FT_Realloc                                                         */
 116   /*                                                                       */
 117   /* <Description>                                                         */
 118   /*    Reallocates a block of memory pointed to by `*P' to `Size' bytes   */
 119   /*    from the heap, possibly changing `*P'.                             */
 120   /*                                                                       */
 121   /* <Input>                                                               */
 122   /*    memory  :: A handle to a given `memory object' which handles       */
 123   /*               reallocation.                                           */
 124   /*                                                                       */
 125   /*    current :: The current block size in bytes.                        */
 126   /*                                                                       */
 127   /*    size    :: The new block size in bytes.                            */
 128   /*                                                                       */
 129   /* <InOut>                                                               */
 130   /*    P       :: A pointer to the fresh new block.  It should be set to  */
 131   /*               NULL if `size' is 0, or in case of error.               */
 132   /*                                                                       */
 133   /* <Return>                                                              */
 134   /*    FreeType error code.  0 means success.                             */
 135   /*                                                                       */
 136   /* <Note>                                                                */
 137   /*    All callers of FT_Realloc() _must_ provide the current block size  */
 138   /*    as well as the new one.                                            */
 139   /*                                                                       */
 140   FT_BASE( FT_Error )
 141   FT_Realloc( FT_Memory  memory,
 142               FT_Long    current,
 143               FT_Long    size,
 144               void**     P );
 145
 146
 147   /*************************************************************************/
 148   /*                                                                       */
 149   /* <Function>                                                            */
 150   /*    FT_Free                                                            */
 151   /*                                                                       */
 152   /* <Description>                                                         */
 153   /*    Releases a given block of memory allocated through FT_Alloc().     */
 154   /*                                                                       */
 155   /* <Input>                                                               */
 156   /*    memory :: A handle to a given `memory object' which handles        */
 157   /*              memory deallocation                                      */
 158   /*                                                                       */
 159   /*    P      :: This is the _address_ of a _pointer_ which points to the */
 160   /*              allocated block.  It is always set to NULL on exit.      */
 161   /*                                                                       */
 162   /* <Return>                                                              */
 163   /*    FreeType error code.  0 means success.                             */
 164   /*                                                                       */
 165   /* <Note>                                                                */
 166   /*    If P or *P are NULL, this function should return successfully.     */
 167   /*    This is a strong convention within all of FreeType and its         */
 168   /*    drivers.                                                           */
 169   /*                                                                       */
 170   FT_BASE( void )
 171   FT_Free( FT_Memory  memory,
 172            void**     P );
 173
 174
 175 #define FT_MEM_SET( dest, byte, count )     ft_memset( dest, byte, count )
 176
 177 #define FT_MEM_COPY( dest, source, count )  ft_memcpy( dest, source, count )
 178
 179 #define FT_MEM_MOVE( dest, source, count )  ft_memmove( dest, source, count )
 180
 181
 182 #define FT_MEM_ZERO( dest, count )  FT_MEM_SET( dest, 0, count )
 183
 184 #define FT_ZERO( p )                FT_MEM_ZERO( p, sizeof ( *(p) ) )
 185
 186
 187   /*************************************************************************/
 188   /*                                                                       */
 189   /* We first define FT_MEM_ALLOC, FT_MEM_REALLOC, and FT_MEM_FREE.  All   */
 190   /* macros use an _implicit_ `memory' parameter to access the current     */
 191   /* memory allocator.                                                     */
 192   /*                                                                       */
 193
 194 #ifdef FT_DEBUG_MEMORY
 195
 196 #define FT_MEM_ALLOC( _pointer_, _size_ )                            \
 197           FT_Alloc_Debug( memory, _size_,                            \
 198                           (void**)&(_pointer_), __FILE__, __LINE__ )
 199
 200 #define FT_MEM_REALLOC( _pointer_, _current_, _size_ )                 \
 201           FT_Realloc_Debug( memory, _current_, _size_,                 \
 202                             (void**)&(_pointer_), __FILE__, __LINE__ )
 203
 204 #define FT_MEM_FREE( _pointer_ )                                            \
 205           FT_Free_Debug( memory, (void**)&(_pointer_), __FILE__, __LINE__ )
 206
 207
 208 #else  /* !FT_DEBUG_MEMORY */
 209
 210
 211 #define FT_MEM_ALLOC( _pointer_, _size_ )                  \
 212           FT_Alloc( memory, _size_, (void**)&(_pointer_) )
 213
 214 #define FT_MEM_FREE( _pointer_ )                  \
 215           FT_Free( memory, (void**)&(_pointer_) )
 216
 217 #define FT_MEM_REALLOC( _pointer_, _current_, _size_ )                  \
 218           FT_Realloc( memory, _current_, _size_, (void**)&(_pointer_) )
 219
 220
 221 #endif /* !FT_DEBUG_MEMORY */
 222
 223
 224   /*************************************************************************/
 225   /*                                                                       */
 226   /* The following functions macros expect that their pointer argument is  */
 227   /* _typed_ in order to automatically compute array element sizes.        */
 228   /*                                                                       */
 229
 230 #define FT_MEM_NEW( _pointer_ )                               \
 231           FT_MEM_ALLOC( _pointer_, sizeof ( *(_pointer_) ) )
 232
 233 #define FT_MEM_NEW_ARRAY( _pointer_, _count_ )                           \
 234           FT_MEM_ALLOC( _pointer_, (_count_) * sizeof ( *(_pointer_) ) )
 235
 236 #define FT_MEM_RENEW_ARRAY( _pointer_, _old_, _new_ )                    \
 237           FT_MEM_REALLOC( _pointer_, (_old_) * sizeof ( *(_pointer_) ),  \
 238                                      (_new_) * sizeof ( *(_pointer_) ) )
 239
 240
 241   /*************************************************************************/
 242   /*                                                                       */
 243   /* the following macros are obsolete but kept for compatibility reasons  */
 244   /*                                                                       */
 245
 246 #define FT_MEM_ALLOC_ARRAY( _pointer_, _count_, _type_ )           \
 247           FT_MEM_ALLOC( _pointer_, (_count_) * sizeof ( _type_ ) )
 248
 249 #define FT_MEM_REALLOC_ARRAY( _pointer_, _old_, _new_, _type_ )    \
 250           FT_MEM_REALLOC( _pointer_, (_old_) * sizeof ( _type ),   \
 251                                      (_new_) * sizeof ( _type_ ) )
 252
 253
 254   /*************************************************************************/
 255   /*                                                                       */
 256   /* The following macros are variants of their FT_MEM_XXXX equivalents;   */
 257   /* they are used to set an _implicit_ `error' variable and return TRUE   */
 258   /* if an error occured (i.e. if 'error != 0').                           */
 259   /*                                                                       */
 260
 261 #define FT_ALLOC( _pointer_, _size_ )                       \
 262           FT_SET_ERROR( FT_MEM_ALLOC( _pointer_, _size_ ) )
 263
 264 #define FT_REALLOC( _pointer_, _current_, _size_ )                       \
 265           FT_SET_ERROR( FT_MEM_REALLOC( _pointer_, _current_, _size_ ) )
 266
 267 #define FT_FREE( _pointer_ )       \
 268           FT_MEM_FREE( _pointer_ )
 269
 270 #define FT_NEW( _pointer_ )  \
 271           FT_SET_ERROR( FT_MEM_NEW( _pointer_ ) )
 272
 273 #define FT_NEW_ARRAY( _pointer_, _count_ )  \
 274           FT_SET_ERROR( FT_MEM_NEW_ARRAY( _pointer_, _count_ ) )
 275
 276 #define FT_RENEW_ARRAY( _pointer_, _old_, _new_ )   \
 277           FT_SET_ERROR( FT_MEM_RENEW_ARRAY( _pointer_, _old_, _new_ ) )
 278
 279 #define FT_ALLOC_ARRAY( _pointer_, _count_, _type_ )                    \
 280           FT_SET_ERROR( FT_MEM_ALLOC( _pointer_,                        \
 281                                       (_count_) * sizeof ( _type_ ) ) )
 282
 283 #define FT_REALLOC_ARRAY( _pointer_, _old_, _new_, _type_ )             \
 284           FT_SET_ERROR( FT_MEM_REALLOC( _pointer_,                      \
 285                                         (_old_) * sizeof ( _type_ ),    \
 286                                         (_new_) * sizeof ( _type_ ) ) )
 287
 288  /* */
 289
 290
 291 FT_END_HEADER
 292
 293 #endif /* __FTMEMORY_H__ */
 294
 295
 296 /* END */