freetype2/include/freetype/ftsystem.h

277 lines
8.4 KiB
C

/***************************************************************************/
/* */
/* 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'll 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 :: handle to source memory manager
* size :: 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 :: handle to source memory manager
* block :: address of 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 :: handle to 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:
* note that 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 ::
* alloc ::
* free ::
* realloc ::
*
*/
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 :: handle to source stream
* offset :: offset of read in stream (always from start)
* buffer :: address of read buffer
* count :: number of bytes to read from the stream
*
* @return:
* number of bytes effectively read by the stream
*
* @note:
* this function might be called to perform seek / skip 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 :: handle to 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 stream, 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's often useful during debugging to use it to store
* the stream's filename, where available
*
* read :: the stream's input function
* close :: the stream close function
*
* memory :: 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 */