Improve documentation so that it can be better parsed by docmaker.

Formatting.
This commit is contained in:
Werner Lemberg 2008-05-28 21:51:57 +00:00
parent de0d00556e
commit 0e9b0ec460
6 changed files with 422 additions and 337 deletions

View File

@ -4,7 +4,7 @@
/* */
/* Build macros of the FreeType 2 library. */
/* */
/* Copyright 1996-2001, 2002, 2003, 2004, 2005, 2006, 2007 by */
/* Copyright 1996-2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 by */
/* David Turner, Robert Wilhelm, and Werner Lemberg. */
/* */
/* This file is part of the FreeType project, and may only be used, */
@ -156,6 +156,7 @@
#define FT_CONFIG_MODULES_H <freetype/config/ftmodule.h>
#endif
/* */
/* public headers */

View File

@ -2091,7 +2091,18 @@ FT_BEGIN_HEADER
FT_UInt horiResolution;
FT_UInt vertResolution;
} FT_Size_RequestRec, *FT_Size_Request;
} FT_Size_RequestRec;
/*************************************************************************/
/* */
/* <Struct> */
/* FT_Size_Request */
/* */
/* <Description> */
/* A handle to a size request structure. */
/* */
typedef struct FT_Size_RequestRec_ *FT_Size_Request;
/*************************************************************************/
@ -2489,19 +2500,19 @@ FT_BEGIN_HEADER
#define FT_LOAD_TARGET_LCD_V FT_LOAD_TARGET_( FT_RENDER_MODE_LCD_V )
/*
/**************************************************************************
*
* @macro:
* FT_LOAD_TARGET_MODE
*
* @description:
* Return the @FT_Render_Mode corresponding to a given
* @FT_LOAD_TARGET_XXX value.
*
*/
#define FT_LOAD_TARGET_MODE( x ) ( (FT_Render_Mode)( ( (x) >> 16 ) & 15 ) )
/* */
/*************************************************************************/
/* */

View File

@ -4,7 +4,7 @@
/* */
/* FreeType Cache subsystem (specification). */
/* */
/* Copyright 1996-2001, 2002, 2003, 2004, 2005, 2006, 2007 by */
/* Copyright 1996-2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 by */
/* David Turner, Robert Wilhelm, and Werner Lemberg. */
/* */
/* This file is part of the FreeType project, and may only be used, */
@ -434,7 +434,18 @@ FT_BEGIN_HEADER
FT_UInt x_res;
FT_UInt y_res;
} FTC_ScalerRec, *FTC_Scaler;
} FTC_ScalerRec;
/*************************************************************************/
/* */
/* <Struct> */
/* FTC_Scaler */
/* */
/* <Description> */
/* A handle to an @FTC_ScalerRec structure. */
/* */
typedef struct FTC_ScalerRec_* FTC_Scaler;
/*************************************************************************/

View File

@ -4,7 +4,7 @@
/* */
/* FreeType incremental loading (specification). */
/* */
/* Copyright 2002, 2003, 2006, 2007 by */
/* Copyright 2002, 2003, 2006, 2007, 2008 by */
/* David Turner, Robert Wilhelm, and Werner Lemberg. */
/* */
/* This file is part of the FreeType project, and may only be used, */
@ -31,192 +31,208 @@
FT_BEGIN_HEADER
/***************************************************************************
*
* @section:
* incremental
*
* @title:
* Incremental Loading
*
* @abstract:
* Custom Glyph Loading.
*
* @description:
* This section contains various functions used to perform so-called
* `incremental' glyph loading. This is a mode where all glyphs loaded
* from a given @FT_Face are provided by the client application,
*
* Apart from that, all other tables are loaded normally from the font
* file. This mode is useful when FreeType is used within another
* engine, e.g., a Postscript Imaging Processor.
*
* To enable this mode, you must use @FT_Open_Face, passing an
* @FT_Parameter with the @FT_PARAM_TAG_INCREMENTAL tag and an
* @FT_Incremental_Interface value. See the comments for
* @FT_Incremental_InterfaceRec for an example.
*
*/
/***************************************************************************
*
* @section:
* incremental
*
* @title:
* Incremental Loading
*
* @abstract:
* Custom Glyph Loading.
*
* @description:
* This section contains various functions used to perform so-called
* `incremental' glyph loading. This is a mode where all glyphs loaded
* from a given @FT_Face are provided by the client application,
*
* Apart from that, all other tables are loaded normally from the font
* file. This mode is useful when FreeType is used within another
* engine, e.g., a Postscript Imaging Processor.
*
* To enable this mode, you must use @FT_Open_Face, passing an
* @FT_Parameter with the @FT_PARAM_TAG_INCREMENTAL tag and an
* @FT_Incremental_Interface value. See the comments for
* @FT_Incremental_InterfaceRec for an example.
*
*/
/***************************************************************************
*
* @type:
* FT_Incremental
*
* @description:
* An opaque type describing a user-provided object used to implement
* `incremental' glyph loading within FreeType. This is used to support
* embedded fonts in certain environments (e.g., Postscript interpreters),
* where the glyph data isn't in the font file, or must be overridden by
* different values.
*
* @note:
* It is up to client applications to create and implement @FT_Incremental
* objects, as long as they provide implementations for the methods
* @FT_Incremental_GetGlyphDataFunc, @FT_Incremental_FreeGlyphDataFunc
* and @FT_Incremental_GetGlyphMetricsFunc.
*
* See the description of @FT_Incremental_InterfaceRec to understand how
* to use incremental objects with FreeType.
*/
/***************************************************************************
*
* @type:
* FT_Incremental
*
* @description:
* An opaque type describing a user-provided object used to implement
* `incremental' glyph loading within FreeType. This is used to support
* embedded fonts in certain environments (e.g., Postscript interpreters),
* where the glyph data isn't in the font file, or must be overridden by
* different values.
*
* @note:
* It is up to client applications to create and implement @FT_Incremental
* objects, as long as they provide implementations for the methods
* @FT_Incremental_GetGlyphDataFunc, @FT_Incremental_FreeGlyphDataFunc
* and @FT_Incremental_GetGlyphMetricsFunc.
*
* See the description of @FT_Incremental_InterfaceRec to understand how
* to use incremental objects with FreeType.
*
*/
typedef struct FT_IncrementalRec_* FT_Incremental;
/***************************************************************************
*
* @struct:
* FT_Incremental_Metrics
*
* @description:
* A small structure used to contain the basic glyph metrics returned
* by the @FT_Incremental_GetGlyphMetricsFunc method.
*
* @fields:
* bearing_x ::
* Left bearing, in font units.
*
* bearing_y ::
* Top bearing, in font units.
*
* advance ::
* Glyph advance, in font units.
*
* @note:
* These correspond to horizontal or vertical metrics depending on the
* value of the `vertical' argument to the function
* @FT_Incremental_GetGlyphMetricsFunc.
*/
/***************************************************************************
*
* @struct:
* FT_Incremental_MetricsRec
*
* @description:
* A small structure used to contain the basic glyph metrics returned
* by the @FT_Incremental_GetGlyphMetricsFunc method.
*
* @fields:
* bearing_x ::
* Left bearing, in font units.
*
* bearing_y ::
* Top bearing, in font units.
*
* advance ::
* Glyph advance, in font units.
*
* @note:
* These correspond to horizontal or vertical metrics depending on the
* value of the `vertical' argument to the function
* @FT_Incremental_GetGlyphMetricsFunc.
*
*/
typedef struct FT_Incremental_MetricsRec_
{
FT_Long bearing_x;
FT_Long bearing_y;
FT_Long advance;
} FT_Incremental_MetricsRec, *FT_Incremental_Metrics;
} FT_Incremental_MetricsRec;
/***************************************************************************
*
* @type:
* FT_Incremental_GetGlyphDataFunc
*
* @description:
* A function called by FreeType to access a given glyph's data bytes
* during @FT_Load_Glyph or @FT_Load_Char if incremental loading is
* enabled.
*
* Note that the format of the glyph's data bytes depends on the font
* file format. For TrueType, it must correspond to the raw bytes within
* the `glyf' table. For Postscript formats, it must correspond to the
* *unencrypted* charstring bytes, without any `lenIV' header. It is
* undefined for any other format.
*
* @input:
* incremental ::
* Handle to an opaque @FT_Incremental handle provided by the client
* application.
*
* glyph_index ::
* Index of relevant glyph.
*
* @output:
* adata ::
* A structure describing the returned glyph data bytes (which will be
* accessed as a read-only byte block).
*
* @return:
* FreeType error code. 0 means success.
*
* @note:
* If this function returns successfully the method
* @FT_Incremental_FreeGlyphDataFunc will be called later to release
* the data bytes.
*
* Nested calls to @FT_Incremental_GetGlyphDataFunc can happen for
* compound glyphs.
*/
/***************************************************************************
*
* @struct:
* FT_Incremental_Metrics
*
* @description:
* A handle to an @FT_Incremental_MetricsRec structure.
*
*/
typedef struct FT_Incremental_MetricsRec_* FT_Incremental_Metrics;
/***************************************************************************
*
* @type:
* FT_Incremental_GetGlyphDataFunc
*
* @description:
* A function called by FreeType to access a given glyph's data bytes
* during @FT_Load_Glyph or @FT_Load_Char if incremental loading is
* enabled.
*
* Note that the format of the glyph's data bytes depends on the font
* file format. For TrueType, it must correspond to the raw bytes within
* the `glyf' table. For Postscript formats, it must correspond to the
* *unencrypted* charstring bytes, without any `lenIV' header. It is
* undefined for any other format.
*
* @input:
* incremental ::
* Handle to an opaque @FT_Incremental handle provided by the client
* application.
*
* glyph_index ::
* Index of relevant glyph.
*
* @output:
* adata ::
* A structure describing the returned glyph data bytes (which will be
* accessed as a read-only byte block).
*
* @return:
* FreeType error code. 0 means success.
*
* @note:
* If this function returns successfully the method
* @FT_Incremental_FreeGlyphDataFunc will be called later to release
* the data bytes.
*
* Nested calls to @FT_Incremental_GetGlyphDataFunc can happen for
* compound glyphs.
*
*/
typedef FT_Error
(*FT_Incremental_GetGlyphDataFunc)( FT_Incremental incremental,
FT_UInt glyph_index,
FT_Data* adata );
/***************************************************************************
*
* @type:
* FT_Incremental_FreeGlyphDataFunc
*
* @description:
* A function used to release the glyph data bytes returned by a
* successful call to @FT_Incremental_GetGlyphDataFunc.
*
* @input:
* incremental ::
* A handle to an opaque @FT_Incremental handle provided by the client
* application.
*
* data ::
* A structure describing the glyph data bytes (which will be accessed
* as a read-only byte block).
*/
/***************************************************************************
*
* @type:
* FT_Incremental_FreeGlyphDataFunc
*
* @description:
* A function used to release the glyph data bytes returned by a
* successful call to @FT_Incremental_GetGlyphDataFunc.
*
* @input:
* incremental ::
* A handle to an opaque @FT_Incremental handle provided by the client
* application.
*
* data ::
* A structure describing the glyph data bytes (which will be accessed
* as a read-only byte block).
*
*/
typedef void
(*FT_Incremental_FreeGlyphDataFunc)( FT_Incremental incremental,
FT_Data* data );
/***************************************************************************
*
* @type:
* FT_Incremental_GetGlyphMetricsFunc
*
* @description:
* A function used to retrieve the basic metrics of a given glyph index
* before accessing its data. This is necessary because, in certain
* formats like TrueType, the metrics are stored in a different place from
* the glyph images proper.
*
* @input:
* incremental ::
* A handle to an opaque @FT_Incremental handle provided by the client
* application.
*
* glyph_index ::
* Index of relevant glyph.
*
* vertical ::
* If true, return vertical metrics.
*
* ametrics ::
* This parameter is used for both input and output.
* The original glyph metrics, if any, in font units. If metrics are
* not available all the values must be set to zero.
*
* @output:
* ametrics ::
* The replacement glyph metrics in font units.
*
*/
/***************************************************************************
*
* @type:
* FT_Incremental_GetGlyphMetricsFunc
*
* @description:
* A function used to retrieve the basic metrics of a given glyph index
* before accessing its data. This is necessary because, in certain
* formats like TrueType, the metrics are stored in a different place from
* the glyph images proper.
*
* @input:
* incremental ::
* A handle to an opaque @FT_Incremental handle provided by the client
* application.
*
* glyph_index ::
* Index of relevant glyph.
*
* vertical ::
* If true, return vertical metrics.
*
* ametrics ::
* This parameter is used for both input and output.
* The original glyph metrics, if any, in font units. If metrics are
* not available all the values must be set to zero.
*
* @output:
* ametrics ::
* The replacement glyph metrics in font units.
*
*/
typedef FT_Error
(*FT_Incremental_GetGlyphMetricsFunc)
( FT_Incremental incremental,
@ -244,6 +260,7 @@ FT_BEGIN_HEADER
* get_glyph_metrics ::
* The function to get glyph metrics. May be null if the font does
* not provide overriding glyph metrics.
*
*/
typedef struct FT_Incremental_FuncsRec_
{
@ -254,41 +271,42 @@ FT_BEGIN_HEADER
} FT_Incremental_FuncsRec;
/***************************************************************************
*
* @struct:
* FT_Incremental_InterfaceRec
*
* @description:
* A structure to be used with @FT_Open_Face to indicate that the user
* wants to support incremental glyph loading. You should use it with
* @FT_PARAM_TAG_INCREMENTAL as in the following example:
*
* {
* FT_Incremental_InterfaceRec inc_int;
* FT_Parameter parameter;
* FT_Open_Args open_args;
*
*
* // set up incremental descriptor
* inc_int.funcs = my_funcs;
* inc_int.object = my_object;
*
* // set up optional parameter
* parameter.tag = FT_PARAM_TAG_INCREMENTAL;
* parameter.data = &inc_int;
*
* // set up FT_Open_Args structure
* open_args.flags = FT_OPEN_PATHNAME | FT_OPEN_PARAMS;
* open_args.pathname = my_font_pathname;
* open_args.num_params = 1;
* open_args.params = &parameter; // we use one optional argument
*
* // open the font
* error = FT_Open_Face( library, &open_args, index, &face );
* ...
* }
*/
/***************************************************************************
*
* @struct:
* FT_Incremental_InterfaceRec
*
* @description:
* A structure to be used with @FT_Open_Face to indicate that the user
* wants to support incremental glyph loading. You should use it with
* @FT_PARAM_TAG_INCREMENTAL as in the following example:
*
* {
* FT_Incremental_InterfaceRec inc_int;
* FT_Parameter parameter;
* FT_Open_Args open_args;
*
*
* // set up incremental descriptor
* inc_int.funcs = my_funcs;
* inc_int.object = my_object;
*
* // set up optional parameter
* parameter.tag = FT_PARAM_TAG_INCREMENTAL;
* parameter.data = &inc_int;
*
* // set up FT_Open_Args structure
* open_args.flags = FT_OPEN_PATHNAME | FT_OPEN_PARAMS;
* open_args.pathname = my_font_pathname;
* open_args.num_params = 1;
* open_args.params = &parameter; // we use one optional argument
*
* // open the font
* error = FT_Open_Face( library, &open_args, index, &face );
* ...
* }
*
*/
typedef struct FT_Incremental_InterfaceRec_
{
const FT_Incremental_FuncsRec* funcs;
@ -297,31 +315,31 @@ FT_BEGIN_HEADER
} FT_Incremental_InterfaceRec;
/***************************************************************************
*
* @type:
* FT_Incremental_Interface
*
* @description:
* A pointer to an @FT_Incremental_InterfaceRec structure.
*
*/
/***************************************************************************
*
* @type:
* FT_Incremental_Interface
*
* @description:
* A pointer to an @FT_Incremental_InterfaceRec structure.
*
*/
typedef FT_Incremental_InterfaceRec* FT_Incremental_Interface;
/***************************************************************************
*
* @constant:
* FT_PARAM_TAG_INCREMENTAL
*
* @description:
* A constant used as the tag of @FT_Parameter structures to indicate
* an incremental loading object to be used by FreeType.
*
*/
/***************************************************************************
*
* @constant:
* FT_PARAM_TAG_INCREMENTAL
*
* @description:
* A constant used as the tag of @FT_Parameter structures to indicate
* an incremental loading object to be used by FreeType.
*
*/
#define FT_PARAM_TAG_INCREMENTAL FT_MAKE_TAG( 'i', 'n', 'c', 'r' )
/* */
/* */
FT_END_HEADER

View File

@ -4,7 +4,7 @@
/* */
/* FreeType API for accessing Windows fnt-specific data. */
/* */
/* Copyright 2003, 2004 by */
/* Copyright 2003, 2004, 2008 by */
/* David Turner, Robert Wilhelm, and Werner Lemberg. */
/* */
/* This file is part of the FreeType project, and may only be used, */
@ -219,36 +219,47 @@ FT_BEGIN_HEADER
FT_UShort color_table_offset;
FT_ULong reserved1[4];
} FT_WinFNT_HeaderRec, *FT_WinFNT_Header;
} FT_WinFNT_HeaderRec;
/**********************************************************************
*
* @function:
* FT_Get_WinFNT_Header
*
* @description:
* Retrieve a Windows FNT font info header.
*
* @input:
* face :: A handle to the input face.
*
* @output:
* aheader :: The WinFNT header.
*
* @return:
* FreeType error code. 0 means success.
*
* @note:
* This function only works with Windows FNT faces, returning an error
* otherwise.
*/
/*************************************************************************/
/* */
/* <Struct> */
/* FT_WinFNT_Header */
/* */
/* <Description> */
/* A handle to an @FT_WinFNT_HeaderRec structure. */
/* */
typedef struct FT_WinFNT_HeaderRec_* FT_WinFNT_Header;
/**********************************************************************
*
* @function:
* FT_Get_WinFNT_Header
*
* @description:
* Retrieve a Windows FNT font info header.
*
* @input:
* face :: A handle to the input face.
*
* @output:
* aheader :: The WinFNT header.
*
* @return:
* FreeType error code. 0 means success.
*
* @note:
* This function only works with Windows FNT faces, returning an error
* otherwise.
*/
FT_EXPORT( FT_Error )
FT_Get_WinFNT_Header( FT_Face face,
FT_WinFNT_HeaderRec *aheader );
/* */
/* */
FT_END_HEADER

View File

@ -5,7 +5,7 @@
/* Basic Type 1/Type 2 tables definitions and interface (specification */
/* only). */
/* */
/* Copyright 1996-2001, 2002, 2003, 2004, 2006 by */
/* Copyright 1996-2001, 2002, 2003, 2004, 2006, 2008 by */
/* David Turner, Robert Wilhelm, and Werner Lemberg. */
/* */
/* This file is part of the FreeType project, and may only be used, */
@ -66,7 +66,7 @@ FT_BEGIN_HEADER
/* that for Multiple Master fonts, each instance has its own */
/* FontInfo dictionary. */
/* */
typedef struct PS_FontInfoRec
typedef struct PS_FontInfoRec_
{
FT_String* version;
FT_String* notice;
@ -78,7 +78,18 @@ FT_BEGIN_HEADER
FT_Short underline_position;
FT_UShort underline_thickness;
} PS_FontInfoRec, *PS_FontInfo;
} PS_FontInfoRec;
/*************************************************************************/
/* */
/* <Struct> */
/* PS_FontInfo */
/* */
/* <Description> */
/* A handle to a @PS_FontInfoRec structure. */
/* */
typedef struct PS_FontInfoRec_* PS_FontInfo;
/*************************************************************************/
@ -142,7 +153,18 @@ FT_BEGIN_HEADER
FT_Short min_feature[2];
} PS_PrivateRec, *PS_Private;
} PS_PrivateRec;
/*************************************************************************/
/* */
/* <Struct> */
/* PS_Private */
/* */
/* <Description> */
/* A handle to a @PS_PrivateRec structure. */
/* */
typedef struct PS_PrivateRec_* PS_Private;
/*************************************************************************/
@ -332,7 +354,18 @@ FT_BEGIN_HEADER
FT_ULong data_offset;
} CID_FaceInfoRec, *CID_FaceInfo;
} CID_FaceInfoRec;
/*************************************************************************/
/* */
/* <Struct> */
/* CID_FaceInfo */
/* */
/* <Description> */
/* A handle to a @CID_FaceInfoRec structure. */
/* */
typedef struct CID_FaceInfoRec_* CID_FaceInfo;
/*************************************************************************/
@ -347,99 +380,99 @@ FT_BEGIN_HEADER
/* */
typedef CID_FaceInfoRec CID_Info;
/* */
/************************************************************************
*
* @function:
* FT_Has_PS_Glyph_Names
*
* @description:
* Return true if a given face provides reliable Postscript glyph
* names. This is similar to using the @FT_HAS_GLYPH_NAMES macro,
* except that certain fonts (mostly TrueType) contain incorrect
* glyph name tables.
*
* When this function returns true, the caller is sure that the glyph
* names returned by @FT_Get_Glyph_Name are reliable.
*
* @input:
* face ::
* face handle
*
* @return:
* Boolean. True if glyph names are reliable.
*/
/************************************************************************
*
* @function:
* FT_Has_PS_Glyph_Names
*
* @description:
* Return true if a given face provides reliable Postscript glyph
* names. This is similar to using the @FT_HAS_GLYPH_NAMES macro,
* except that certain fonts (mostly TrueType) contain incorrect
* glyph name tables.
*
* When this function returns true, the caller is sure that the glyph
* names returned by @FT_Get_Glyph_Name are reliable.
*
* @input:
* face ::
* face handle
*
* @return:
* Boolean. True if glyph names are reliable.
*
*/
FT_EXPORT( FT_Int )
FT_Has_PS_Glyph_Names( FT_Face face );
/************************************************************************
*
* @function:
* FT_Get_PS_Font_Info
*
* @description:
* Retrieve the @PS_FontInfoRec structure corresponding to a given
* Postscript font.
*
* @input:
* face ::
* Postscript face handle.
*
* @output:
* afont_info ::
* Output font info structure pointer.
*
* @return:
* FreeType error code. 0 means success.
*
* @note:
* The string pointers within the font info structure are owned by
* the face and don't need to be freed by the caller.
*
* If the font's format is not Postscript-based, this function will
* return the `FT_Err_Invalid_Argument' error code.
*/
/************************************************************************
*
* @function:
* FT_Get_PS_Font_Info
*
* @description:
* Retrieve the @PS_FontInfoRec structure corresponding to a given
* Postscript font.
*
* @input:
* face ::
* Postscript face handle.
*
* @output:
* afont_info ::
* Output font info structure pointer.
*
* @return:
* FreeType error code. 0 means success.
*
* @note:
* The string pointers within the font info structure are owned by
* the face and don't need to be freed by the caller.
*
* If the font's format is not Postscript-based, this function will
* return the `FT_Err_Invalid_Argument' error code.
*
*/
FT_EXPORT( FT_Error )
FT_Get_PS_Font_Info( FT_Face face,
PS_FontInfoRec *afont_info );
FT_Get_PS_Font_Info( FT_Face face,
PS_FontInfo afont_info );
/************************************************************************
*
* @function:
* FT_Get_PS_Font_Private
*
* @description:
* Retrieve the @PS_PrivateRec structure corresponding to a given
* Postscript font.
*
* @input:
* face ::
* Postscript face handle.
*
* @output:
* afont_private ::
* Output private dictionary structure pointer.
*
* @return:
* FreeType error code. 0 means success.
*
* @note:
* The string pointers within the font info structure are owned by
* the face and don't need to be freed by the caller.
*
* If the font's format is not Postscript-based, this function will
* return the `FT_Err_Invalid_Argument' error code.
*/
/************************************************************************
*
* @function:
* FT_Get_PS_Font_Private
*
* @description:
* Retrieve the @PS_PrivateRec structure corresponding to a given
* Postscript font.
*
* @input:
* face ::
* Postscript face handle.
*
* @output:
* afont_private ::
* Output private dictionary structure pointer.
*
* @return:
* FreeType error code. 0 means success.
*
* @note:
* The string pointers within the font info structure are owned by
* the face and don't need to be freed by the caller.
*
* If the font's format is not Postscript-based, this function will
* return the `FT_Err_Invalid_Argument' error code.
*
*/
FT_EXPORT( FT_Error )
FT_Get_PS_Font_Private( FT_Face face,
PS_PrivateRec *afont_private );
/* */
FT_Get_PS_Font_Private( FT_Face face,
PS_Private afont_private );
/* */
FT_END_HEADER