freetype2/include/freetype/ftsystem.h

/***************************************************************************/
/*                                                                         */
/*  ftsystem.h                                                             */
/*                                                                         */
/*    FreeType low-level system interface definition (specification).      */
/*                                                                         */
/*  Copyright 1996-2000 by                                                 */
/*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
/*                                                                         */
/*  This file is part of the FreeType project, and may only be used,       */
/*  modified, and distributed under the terms of the FreeType project      */
/*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
/*  this file you indicate that you have read the license and              */
/*  understand and accept it fully.                                        */
/*                                                                         */
/***************************************************************************/


#ifndef __FTSYSTEM_H__
#define __FTSYSTEM_H__


#include <ft2build.h>


FT_BEGIN_HEADER

  /*************************************************************************/
  /*                                                                       */
  /* <Section>                                                             */
  /*    system_interface                                                   */
  /*                                                                       */
  /* <Title>                                                               */
  /*    System Interface                                                   */
  /*                                                                       */
  /* <Abstract>                                                            */
  /*    How FreeType manages memory and i/o.                               */
  /*                                                                       */
  /* <Description>                                                         */
  /*    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.                                                 */
  /*                                                                       */
  /*************************************************************************/


  /*************************************************************************/
  /*                                                                       */
  /*                  M E M O R Y   M A N A G E M E N T                    */
  /*                                                                       */
  /*************************************************************************/


  /*************************************************************************/
  /*                                                                       */
  /* @type:                                                                */
  /*    FT_Memory                                                          */
  /*                                                                       */
  /* @description:                                                         */
  /*    A handle to a given memory manager object, defined with a          */
  /*    @FT_MemoryRec structure.                                           */
  /*                                                                       */
  typedef struct FT_MemoryRec_*  FT_Memory;


  /*************************************************************************/
  /*                                                                       */
  /* @functype:                                                            */
  /*    FT_Alloc_Func                                                      */
  /*                                                                       */
  /* @description:                                                         */
  /*    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.                */
  /*                                                                       */
  typedef void*  (*FT_Alloc_Func)( FT_Memory  memory,
                                   long       size );


  /*************************************************************************/
  /*                                                                       */
  /* @functype:                                                            */
  /*    FT_Free_Func                                                       */
  /*                                                                       */
  /* @description:                                                         */
  /*    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.                  */
  /*                                                                       */
  typedef void   (*FT_Free_Func)( FT_Memory  memory,
                                  void*      block );


  /*************************************************************************/
  /*                                                                       */
  /* @functype:                                                            */
  /*    FT_Realloc_Func                                                    */
  /*                                                                       */
  /* @description:                                                         */
  /*    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.            */
  /*                                                                       */
  typedef void*  (*FT_Realloc_Func)( FT_Memory  memory,
                                     long       cur_size,
                                     long       new_size,
                                     void*      block );


  /*************************************************************************/
  /*                                                                       */
  /* @struct:                                                              */
  /*    FT_MemoryRec                                                       */
  /*                                                                       */
  /* @description:                                                         */
  /*    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.              */
  /*                                                                       */
  struct  FT_MemoryRec_
  {
    void*            user;
    FT_Alloc_Func    alloc;
    FT_Free_Func     free;
    FT_Realloc_Func  realloc;
  };


  /*************************************************************************/
  /*                                                                       */
  /*                       I / O   M A N A G E M E N T                     */
  /*                                                                       */
  /*************************************************************************/


  /*************************************************************************/
  /*                                                                       */
  /* @type:                                                                */
  /*    FT_Stream                                                          */
  /*                                                                       */
  /* @description:                                                         */
  /*    A handle to an input stream.                                       */
  /*                                                                       */
  typedef struct FT_StreamRec_*  FT_Stream;


  /*************************************************************************/
  /*                                                                       */
  /* @struct:                                                              */
  /*    FT_StreamDesc                                                      */
  /*                                                                       */
  /* @description:                                                         */
  /*    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.     */
  /*                                                                       */
  typedef union  FT_StreamDesc_
  {
    long   value;
    void*  pointer;

  } FT_StreamDesc;


  /*************************************************************************/
  /*                                                                       */
  /* @functype:                                                            */
  /*    FT_Stream_IO                                                       */
  /*                                                                       */
  /* @description:                                                         */
  /*    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.                                               */
  /*                                                                       */
  typedef unsigned long  (*FT_Stream_IO)( FT_Stream       stream,
                                          unsigned long   offset,
                                          unsigned char*  buffer,
                                          unsigned long   count );


  /*************************************************************************/
  /*                                                                       */
  /* @functype:                                                            */
  /*    FT_Stream_Close                                                    */
  /*                                                                       */
  /* @description:                                                         */
  /*    A function used to close a given input stream.                     */
  /*                                                                       */
  /* @input:                                                               */
  /*   stream :: A handle to the target stream.                            */
  /*                                                                       */
  typedef void  (*FT_Stream_Close)( FT_Stream  stream );


  /*************************************************************************/
  /*                                                                       */
  /* @struct:                                                              */
  /*    FT_StreamRec                                                       */
  /*                                                                       */
  /* @description:                                                         */
  /*   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.                                  */
  /*                                                                       */
  struct  FT_StreamRec_
  {
    unsigned char*   base;
    unsigned long    size;
    unsigned long    pos;

    FT_StreamDesc    descriptor;
    FT_StreamDesc    pathname;
    FT_Stream_IO     read;
    FT_Stream_Close  close;

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


  /* */


FT_END_HEADER

#endif /* __FTSYSTEM_H__ */


/* END */