ref: c43fd3a749d9659277568b6cce6539d6f5503883
parent: 8edbcabce1b3756fb1921f85901dcce944bdf1e7
author: Werner Lemberg <[email protected]>
date: Tue Jun 19 05:11:18 EDT 2001
Formatting.
--- a/include/freetype/ftsystem.h
+++ b/include/freetype/ftsystem.h
@@ -25,23 +25,26 @@
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
- *
- */
+ /*************************************************************************/
+ /* */
+ /* <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 */
@@ -48,68 +51,79 @@
/* */
/*************************************************************************/
- /**********************************************************************
- *
- * @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,
@@ -116,21 +130,24 @@
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 @@
/*************************************************************************/
- /************************************************************************
- *
- * @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_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;