# FreeType-2.1.8 API Reference

# System Interface

## Synopsis

| FT_Memory |  | FT_MemoryRec |  | FT_Stream_CloseFunc
| FT_Alloc_Func |  | FT_Stream |  | FT_StreamRec
| FT_Free_Func |  | FT_StreamDesc |  |
| FT_Realloc_Func |  | FT_Stream_IoFunc |  |

This section contains various definitions related to memory management and i/o access. You need to understand this information if you want to use a custom memory manager or you own input i/o streams.

#### FT_Memory

      typedef struct FT_MemoryRec_*  FT_Memory;

A handle to a given memory manager object, defined with a FT_MemoryRec structure.

#### FT_Alloc_Func

      typedef void*
      (*FT_Alloc_Func)( FT_Memory  memory,
                        long       size );

A function used to allocate `size' bytes from `memory'.

input

memory | A handle to the source memory manager.
size | The size in bytes to allocate.

return
Address of new memory block. 0 in case of failure.

#### FT_Free_Func

      typedef void
      (*FT_Free_Func)( FT_Memory  memory,
                       void*      block );

A function used to release a given block of memory.

input

memory | A handle to the source memory manager.
block | The address of the target memory block.

#### FT_Realloc_Func

      typedef void*
      (*FT_Realloc_Func)( FT_Memory  memory,
                          long       cur_size,
                          long       new_size,
                          void*      block );

a function used to re-allocate a given block of memory.

input

memory | A handle to the source memory manager.
cur_size | The block's current size in bytes.
new_size | The block's requested new size.
block | The block's current address.

return
New block address. 0 in case of memory shortage.

note
In case of error, the old block must still be available.

#### FT_MemoryRec

      struct  FT_MemoryRec_
      {
        void*            user;
        FT_Alloc_Func    alloc;
        FT_Free_Func     free;
        FT_Realloc_Func  realloc;
      };

A structure used to describe a given memory manager to FreeType 2.

fields

user | A generic typeless pointer for user data.
alloc | A pointer type to an allocation function.
free | A pointer type to an memory freeing function.
realloc | A pointer type to a reallocation function.

#### FT_Stream

      typedef struct FT_StreamRec_*  FT_Stream;

A handle to an input stream.

#### FT_StreamDesc

      typedef union  FT_StreamDesc_
      {
        long   value;
        void*  pointer;

      } FT_StreamDesc;

A union type used to store either a long or a pointer. This is used to store a file descriptor or a FILE* in an input stream.

#### FT_Stream_IoFunc

      typedef unsigned long
      (*FT_Stream_IoFunc)( FT_Stream       stream,
                           unsigned long   offset,
                           unsigned char*  buffer,
                           unsigned long   count );

A function used to seek and read data from a given input stream.

input

stream | A handle to the source stream.
offset | The offset of read in stream (always from start).
buffer | The address of the read buffer.
count | The number of bytes to read from the stream.

return
The number of bytes effectively read by the stream.

note
This function might be called to perform a seek or skip operation with a `count' of 0.

#### FT_Stream_CloseFunc

      typedef void
      (*FT_Stream_CloseFunc)( FT_Stream  stream );

A function used to close a given input stream.

input

stream | A handle to the target stream.

#### FT_StreamRec

      typedef struct  FT_StreamRec_
      {
        unsigned char*       base;
        unsigned long        size;
        unsigned long        pos;

        FT_StreamDesc        descriptor;
        FT_StreamDesc        pathname;
        FT_Stream_IoFunc     read;
        FT_Stream_CloseFunc  close;

        FT_Memory            memory;
        unsigned char*       cursor;
        unsigned char*       limit;

      } FT_StreamRec;

A structure used to describe an input stream.

input

base | For memory-based streams, this is the address of the first stream byte in memory. This field should always be set to NULL for disk-based streams.
size | The stream size in bytes.
pos | The current position within the stream.
descriptor | This field is a union that can hold an integer or a pointer. It is used by stream implementations to store file descriptors or FILE* pointers.
pathname | This field is completely ignored by FreeType. However, it is often useful during debugging to use it to store the stream's filename (where available).
read | The stream's input function.
close | The stream;s close function.
memory | The memory manager to use to preload frames. This is set internally by FreeType and shouldn't be touched by stream implementations.
cursor | This field is set and used internally by FreeType when parsing frames.
limit | This field is set and used internally by FreeType when parsing frames.