diff --git a/include/freetype/ftsystem.h b/include/freetype/ftsystem.h index f355421d2..151a80f6f 100644 --- a/include/freetype/ftsystem.h +++ b/include/freetype/ftsystem.h @@ -25,22 +25,25 @@ FT_BEGIN_HEADER - /************************************************************************** - * - *
system_interface - * - * 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 - * - */ + /*************************************************************************/ + /* */ + /* <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. */ + /* */ + /*************************************************************************/ + /*************************************************************************/ /* */ @@ -48,89 +51,103 @@ FT_BEGIN_HEADER /* */ /*************************************************************************/ - /********************************************************************** - * - * @type: FT_Memory - * - * @description: - * a handle to a given memory manager object, defined with a - * @FT_MemoryRec structure. - */ + + /*************************************************************************/ + /* */ + /* @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 - */ + /*************************************************************************/ + /* */ + /* @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 :: handle to source memory manager - * block :: address of target memory block - */ + /*************************************************************************/ + /* */ + /* @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 :: 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 - */ + + /*************************************************************************/ + /* */ + /* @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 :: - * alloc :: - * free :: - * realloc :: - * - */ - struct FT_MemoryRec_ + /*************************************************************************/ + /* */ + /* @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; @@ -146,26 +163,26 @@ FT_BEGIN_HEADER /*************************************************************************/ - /************************************************************************ - * - * @type: FT_Stream - * - * @description: - * a handle to an input stream. - */ + /*************************************************************************/ + /* */ + /* @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 - * - */ + /*************************************************************************/ + /* */ + /* @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; @@ -174,80 +191,89 @@ FT_BEGIN_HEADER } 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 - */ + /*************************************************************************/ + /* */ + /* @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 :: handle to target stream - */ + + /*************************************************************************/ + /* */ + /* @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 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 */ + /* */ + /* @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;