minhngoc25a
/
freetype2
mirror of git://git.savannah.gnu.org/freetype/freetype2.git
2
1
Fork 2
Code Issues 4 Releases Wiki Activity

API documentation: Re-organize chapters and sections 

* Split the very long 'Base Interface' section into smaller sections.
* Split the 'Core API' chapter into two chapters.
* Remove single enumeration values from `@order` fields since they have no
  effect.
This commit is contained in:
Werner Lemberg 2023-04-24 09:48:09 +02:00
parent c4fe77c3f0
commit 70d001616b
2 changed files with 413 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

509
include/freetype/freetype.h
View File

@ -102,61 +102,25 @@ FT_BEGIN_HEADER
*/ */
/*************************************************************************/
/*************************************************************************/
/* */
/* B A S I C T Y P E S */
/* */
/*************************************************************************/
/*************************************************************************/
/************************************************************************** /**************************************************************************
* *
* @section: * @section:
* base_interface * font_testing_macros
* *
* @title: * @title:
* Base Interface * Font Testing Macros
* *
* @abstract: * @abstract:
* The FreeType~2 base font interface. * Macros to test various properties of fonts.
* *
* @description: * @description:
* This section describes the most important public high-level API * Macros to test the most important font properties.
* functions of FreeType~2. *
* It is recommended to use these high-level macros instead of directly
* testing the corresponding flags, which are scattered over various
* structures.
* *
* @order: * @order:
* FT_Library
* FT_Face
* FT_Size
* FT_GlyphSlot
* FT_CharMap
* FT_Encoding
* FT_ENC_TAG
*
* FT_FaceRec
*
* FT_FACE_FLAG_SCALABLE
* FT_FACE_FLAG_FIXED_SIZES
* FT_FACE_FLAG_FIXED_WIDTH
* FT_FACE_FLAG_HORIZONTAL
* FT_FACE_FLAG_VERTICAL
* FT_FACE_FLAG_COLOR
* FT_FACE_FLAG_SFNT
* FT_FACE_FLAG_CID_KEYED
* FT_FACE_FLAG_TRICKY
* FT_FACE_FLAG_KERNING
* FT_FACE_FLAG_MULTIPLE_MASTERS
* FT_FACE_FLAG_VARIATION
* FT_FACE_FLAG_GLYPH_NAMES
* FT_FACE_FLAG_EXTERNAL_STREAM
* FT_FACE_FLAG_HINTER
* FT_FACE_FLAG_SVG
* FT_FACE_FLAG_SBIX
* FT_FACE_FLAG_SBIX_OVERLAY
*
* FT_HAS_HORIZONTAL * FT_HAS_HORIZONTAL
* FT_HAS_VERTICAL * FT_HAS_VERTICAL
* FT_HAS_KERNING * FT_HAS_KERNING
@ -176,21 +140,59 @@ FT_BEGIN_HEADER
* FT_IS_NAMED_INSTANCE * FT_IS_NAMED_INSTANCE
* FT_IS_VARIATION * FT_IS_VARIATION
* *
* FT_STYLE_FLAG_BOLD */
* FT_STYLE_FLAG_ITALIC
/**************************************************************************
* *
* FT_SizeRec * @section:
* FT_Size_Metrics * library_setup
* *
* FT_GlyphSlotRec * @title:
* FT_Glyph_Metrics * Library Setup
* FT_SubGlyph
* *
* FT_Bitmap_Size * @abstract:
* Functions to start and end the usage of the FreeType library.
* *
* @description:
* Functions to start and end the usage of the FreeType library.
*
* Note that @FT_Library_Version and @FREETYPE_XXX are of limited use
* because even a new release of FreeType with only documentation
* changes increases the version number.
*
* @order:
* FT_Library
* FT_Init_FreeType * FT_Init_FreeType
* FT_Done_FreeType * FT_Done_FreeType
* *
* FT_Library_Version
* FREETYPE_XXX
*
*/
/**************************************************************************
*
* @section:
* face_creation
*
* @title:
* Face Creation
*
* @abstract:
* Functions to manage fonts.
*
* @description:
* The functions and structures collected in this section operate on
* fonts globally.
*
* @order:
* FT_Face
* FT_FaceRec
* FT_FACE_FLAG_XXX
* FT_STYLE_FLAG_XXX
*
* FT_New_Face * FT_New_Face
* FT_Done_Face * FT_Done_Face
* FT_Reference_Face * FT_Reference_Face
@ -198,10 +200,36 @@ FT_BEGIN_HEADER
* FT_Face_Properties * FT_Face_Properties
* FT_Open_Face * FT_Open_Face
* FT_Open_Args * FT_Open_Args
* FT_OPEN_XXX
* FT_Parameter * FT_Parameter
* FT_Attach_File * FT_Attach_File
* FT_Attach_Stream * FT_Attach_Stream
* *
*/
/**************************************************************************
*
* @section:
* sizing_and_scaling
*
* @title:
* Sizing and Scaling
*
* @abstract:
* Functions to manage font sizes.
*
* @description:
* The functions and structures collected in this section are related to
* selecting and manipulating the size of a font globally.
*
* @order:
* FT_Size
* FT_SizeRec
* FT_Size_Metrics
*
* FT_Bitmap_Size
*
* FT_Set_Char_Size * FT_Set_Char_Size
* FT_Set_Pixel_Sizes * FT_Set_Pixel_Sizes
* FT_Request_Size * FT_Request_Size
@ -209,44 +237,37 @@ FT_BEGIN_HEADER
* FT_Size_Request_Type * FT_Size_Request_Type
* FT_Size_RequestRec * FT_Size_RequestRec
* FT_Size_Request * FT_Size_Request
*
* FT_Set_Transform * FT_Set_Transform
* FT_Get_Transform * FT_Get_Transform
*
*/
/**************************************************************************
*
* @section:
* glyph_retrieval
*
* @title:
* Glyph Retrieval
*
* @abstract:
* Functions to manage glyphs.
*
* @description:
* The functions and structures collected in this section operate on
* single glyphs, of which @FT_Load_Glyph is most important.
*
* @order:
* FT_GlyphSlot
* FT_GlyphSlotRec
* FT_Glyph_Metrics
*
* FT_Load_Glyph * FT_Load_Glyph
* FT_Get_Char_Index * FT_LOAD_XXX
* FT_Get_First_Char
* FT_Get_Next_Char
* FT_Load_Char
*
* FT_OPEN_MEMORY
* FT_OPEN_STREAM
* FT_OPEN_PATHNAME
* FT_OPEN_DRIVER
* FT_OPEN_PARAMS
*
* FT_LOAD_DEFAULT
* FT_LOAD_RENDER
* FT_LOAD_MONOCHROME
* FT_LOAD_LINEAR_DESIGN
* FT_LOAD_NO_SCALE
* FT_LOAD_NO_HINTING
* FT_LOAD_NO_BITMAP
* FT_LOAD_SBITS_ONLY
* FT_LOAD_NO_AUTOHINT
* FT_LOAD_COLOR
*
* FT_LOAD_VERTICAL_LAYOUT
* FT_LOAD_IGNORE_TRANSFORM
* FT_LOAD_FORCE_AUTOHINT
* FT_LOAD_NO_RECURSE
* FT_LOAD_PEDANTIC
*
* FT_LOAD_TARGET_NORMAL
* FT_LOAD_TARGET_LIGHT
* FT_LOAD_TARGET_MONO
* FT_LOAD_TARGET_LCD
* FT_LOAD_TARGET_LCD_V
*
* FT_LOAD_TARGET_MODE * FT_LOAD_TARGET_MODE
* FT_LOAD_TARGET_XXX
* *
* FT_Render_Glyph * FT_Render_Glyph
* FT_Render_Mode * FT_Render_Mode
@ -254,34 +275,121 @@ FT_BEGIN_HEADER
* FT_Kerning_Mode * FT_Kerning_Mode
* FT_Get_Track_Kerning * FT_Get_Track_Kerning
* *
*/
/**************************************************************************
*
* @section:
* character_mapping
*
* @title:
* Character Mapping
*
* @abstract:
* Functions to manage character-to-glyph maps.
*
* @description:
* This section holds functions and structures that are related to
* mapping character input codes to glyph indices.
*
* Note that for many scripts the simplistic approach used by FreeType
* of mapping a single character to a single glyph is not valid or
* possible! In general, a higher-level library like HarfBuzz or ICU
* should be used for handling text strings.
*
* @order:
* FT_CharMap
* FT_CharMapRec * FT_CharMapRec
* FT_Encoding
* FT_ENC_TAG
*
* FT_Select_Charmap * FT_Select_Charmap
* FT_Set_Charmap * FT_Set_Charmap
* FT_Get_Charmap_Index * FT_Get_Charmap_Index
* *
* FT_Get_Char_Index
* FT_Get_First_Char
* FT_Get_Next_Char
* FT_Load_Char
*
*/
/**************************************************************************
*
* @section:
* information_retrieval
*
* @title:
* Information Retrieval
*
* @abstract:
* Functions to retrieve font and glyph information.
*
* @description:
* Functions to retrieve font and glyph information. Only some very
* basic data is covered; see also the chapter on the format-specific
* API for more.
*
*
* @order:
* FT_Get_Name_Index * FT_Get_Name_Index
* FT_Get_Glyph_Name * FT_Get_Glyph_Name
* FT_Get_Postscript_Name * FT_Get_Postscript_Name
* FT_Get_FSType_Flags * FT_Get_FSType_Flags
* FT_FSTYPE_XXX
* FT_Get_SubGlyph_Info * FT_Get_SubGlyph_Info
* FT_SUBGLYPH_FLAG_XXX
* *
*/
/**************************************************************************
*
* @section:
* other_api_data
*
* @title:
* Other API Data
*
* @abstract:
* Other structures, enumerations, and macros.
*
* @description:
* Other structures, enumerations, and macros. Deprecated functions are
* also listed here.
*
* @order:
* FT_Face_Internal * FT_Face_Internal
* FT_Size_Internal * FT_Size_Internal
* FT_Slot_Internal * FT_Slot_Internal
* *
* FT_FACE_FLAG_XXX * FT_SubGlyph
* FT_STYLE_FLAG_XXX
* FT_OPEN_XXX
* FT_LOAD_XXX
* FT_LOAD_TARGET_XXX
* FT_SUBGLYPH_FLAG_XXX
* FT_FSTYPE_XXX
* *
* FT_HAS_FAST_GLYPHS * FT_HAS_FAST_GLYPHS
* FT_Face_CheckTrueTypePatents
* FT_Face_SetUnpatentedHinting
* *
*/ */
/*************************************************************************/
/*************************************************************************/
/* */
/* B A S I C T Y P E S */
/* */
/*************************************************************************/
/*************************************************************************/
/**************************************************************************
*
* @section:
* glyph_retrieval
*
*/
/************************************************************************** /**************************************************************************
* *
* @struct: * @struct:
@ -349,6 +457,13 @@ FT_BEGIN_HEADER
} FT_Glyph_Metrics; } FT_Glyph_Metrics;
/**************************************************************************
*
* @section:
* sizing_and_scaling
*
*/
/************************************************************************** /**************************************************************************
* *
* @struct: * @struct:
@ -409,6 +524,13 @@ FT_BEGIN_HEADER
/*************************************************************************/ /*************************************************************************/
/*************************************************************************/ /*************************************************************************/
/**************************************************************************
*
* @section:
* library_setup
*
*/
/************************************************************************** /**************************************************************************
* *
* @type: * @type:
@ -483,7 +605,7 @@ FT_BEGIN_HEADER
/************************************************************************** /**************************************************************************
* *
* @section: * @section:
* base_interface * face_creation
* *
*/ */
@ -519,6 +641,13 @@ FT_BEGIN_HEADER
typedef struct FT_FaceRec_* FT_Face; typedef struct FT_FaceRec_* FT_Face;
/**************************************************************************
*
* @section:
* sizing_and_scaling
*
*/
/************************************************************************** /**************************************************************************
* *
* @type: * @type:
@ -551,6 +680,13 @@ FT_BEGIN_HEADER
typedef struct FT_SizeRec_* FT_Size; typedef struct FT_SizeRec_* FT_Size;
/**************************************************************************
*
* @section:
* glyph_retrieval
*
*/
/************************************************************************** /**************************************************************************
* *
* @type: * @type:
@ -570,6 +706,13 @@ FT_BEGIN_HEADER
typedef struct FT_GlyphSlotRec_* FT_GlyphSlot; typedef struct FT_GlyphSlotRec_* FT_GlyphSlot;
/**************************************************************************
*
* @section:
* character_mapping
*
*/
/************************************************************************** /**************************************************************************
* *
* @type: * @type:
@ -877,6 +1020,13 @@ FT_BEGIN_HEADER
/*************************************************************************/ /*************************************************************************/
/**************************************************************************
*
* @section:
* other_api_data
*
*/
/************************************************************************** /**************************************************************************
* *
* @type: * @type:
@ -892,6 +1042,13 @@ FT_BEGIN_HEADER
typedef struct FT_Face_InternalRec_* FT_Face_Internal; typedef struct FT_Face_InternalRec_* FT_Face_Internal;
/**************************************************************************
*
* @section:
* face_creation
*
*/
/************************************************************************** /**************************************************************************
* *
* @struct: * @struct:
@ -1272,6 +1429,13 @@ FT_BEGIN_HEADER
#define FT_FACE_FLAG_SBIX_OVERLAY ( 1L << 18 ) #define FT_FACE_FLAG_SBIX_OVERLAY ( 1L << 18 )
/**************************************************************************
*
* @section:
* font_testing_macros
*
*/
/************************************************************************** /**************************************************************************
* *
* @macro: * @macro:
@ -1381,6 +1545,13 @@ FT_BEGIN_HEADER
( !!( (face)->face_flags & FT_FACE_FLAG_FIXED_SIZES ) ) ( !!( (face)->face_flags & FT_FACE_FLAG_FIXED_SIZES ) )
/**************************************************************************
*
* @section:
* other_api_data
*
*/
/************************************************************************** /**************************************************************************
* *
* @macro: * @macro:
@ -1393,6 +1564,13 @@ FT_BEGIN_HEADER
#define FT_HAS_FAST_GLYPHS( face ) 0 #define FT_HAS_FAST_GLYPHS( face ) 0
/**************************************************************************
*
* @section:
* font_testing_macros
*
*/
/************************************************************************** /**************************************************************************
* *
* @macro: * @macro:
@ -1628,6 +1806,13 @@ FT_BEGIN_HEADER
( !!( (face)->face_flags & FT_FACE_FLAG_SBIX_OVERLAY ) ) ( !!( (face)->face_flags & FT_FACE_FLAG_SBIX_OVERLAY ) )
/**************************************************************************
*
* @section:
* face_creation
*
*/
/************************************************************************** /**************************************************************************
* *
* @enum: * @enum:
@ -1654,6 +1839,13 @@ FT_BEGIN_HEADER
#define FT_STYLE_FLAG_BOLD ( 1 << 1 ) #define FT_STYLE_FLAG_BOLD ( 1 << 1 )
/**************************************************************************
*
* @section:
* other_api_data
*
*/
/************************************************************************** /**************************************************************************
* *
* @type: * @type:
@ -1666,6 +1858,13 @@ FT_BEGIN_HEADER
typedef struct FT_Size_InternalRec_* FT_Size_Internal; typedef struct FT_Size_InternalRec_* FT_Size_Internal;
/**************************************************************************
*
* @section:
* sizing_and_scaling
*
*/
/************************************************************************** /**************************************************************************
* *
* @struct: * @struct:
@ -1817,6 +2016,13 @@ FT_BEGIN_HEADER
} FT_SizeRec; } FT_SizeRec;
/**************************************************************************
*
* @section:
* other_api_data
*
*/
/************************************************************************** /**************************************************************************
* *
* @struct: * @struct:
@ -1848,6 +2054,13 @@ FT_BEGIN_HEADER
typedef struct FT_Slot_InternalRec_* FT_Slot_Internal; typedef struct FT_Slot_InternalRec_* FT_Slot_Internal;
/**************************************************************************
*
* @section:
* glyph_retrieval
*
*/
/************************************************************************** /**************************************************************************
* *
* @struct: * @struct:
@ -2092,6 +2305,13 @@ FT_BEGIN_HEADER
/*************************************************************************/ /*************************************************************************/
/**************************************************************************
*
* @section:
* library_setup
*
*/
/************************************************************************** /**************************************************************************
* *
* @function: * @function:
@ -2149,6 +2369,13 @@ FT_BEGIN_HEADER
FT_Done_FreeType( FT_Library library ); FT_Done_FreeType( FT_Library library );
/**************************************************************************
*
* @section:
* face_creation
*
*/
/************************************************************************** /**************************************************************************
* *
* @enum: * @enum:
@ -2650,6 +2877,13 @@ FT_BEGIN_HEADER
FT_Done_Face( FT_Face face ); FT_Done_Face( FT_Face face );
/**************************************************************************
*
* @section:
* sizing_and_scaling
*
*/
/************************************************************************** /**************************************************************************
* *
* @function: * @function:
@ -2942,6 +3176,13 @@ FT_BEGIN_HEADER
FT_UInt pixel_height ); FT_UInt pixel_height );
/**************************************************************************
*
* @section:
* glyph_retrieval
*
*/
/************************************************************************** /**************************************************************************
* *
* @function: * @function:
@ -2990,6 +3231,13 @@ FT_BEGIN_HEADER
FT_Int32 load_flags ); FT_Int32 load_flags );
/**************************************************************************
*
* @section:
* character_mapping
*
*/
/************************************************************************** /**************************************************************************
* *
* @function: * @function:
@ -3033,6 +3281,13 @@ FT_BEGIN_HEADER
FT_Int32 load_flags ); FT_Int32 load_flags );
/**************************************************************************
*
* @section:
* glyph_retrieval
*
*/
/************************************************************************** /**************************************************************************
* *
* @enum: * @enum:
@ -3372,6 +3627,13 @@ FT_BEGIN_HEADER
FT_STATIC_CAST( FT_Render_Mode, ( (x) >> 16 ) & 15 ) FT_STATIC_CAST( FT_Render_Mode, ( (x) >> 16 ) & 15 )
/**************************************************************************
*
* @section:
* sizing_and_scaling
*
*/
/************************************************************************** /**************************************************************************
* *
* @function: * @function:
@ -3447,6 +3709,13 @@ FT_BEGIN_HEADER
FT_Vector* delta ); FT_Vector* delta );
/**************************************************************************
*
* @section:
* glyph_retrieval
*
*/
/************************************************************************** /**************************************************************************
* *
* @enum: * @enum:
@ -3841,6 +4110,13 @@ FT_BEGIN_HEADER
FT_Fixed* akerning ); FT_Fixed* akerning );
/**************************************************************************
*
* @section:
* character_mapping
*
*/
/************************************************************************** /**************************************************************************
* *
* @function: * @function:
@ -4057,6 +4333,13 @@ FT_BEGIN_HEADER
FT_UInt *agindex ); FT_UInt *agindex );
/**************************************************************************
*
* @section:
* face_creation
*
*/
/************************************************************************** /**************************************************************************
* *
* @function: * @function:
@ -4155,6 +4438,13 @@ FT_BEGIN_HEADER
FT_Parameter* properties ); FT_Parameter* properties );
/**************************************************************************
*
* @section:
* information_retrieval
*
*/
/************************************************************************** /**************************************************************************
* *
* @function: * @function:
@ -4900,32 +5190,10 @@ FT_BEGIN_HEADER
/************************************************************************** /**************************************************************************
* *
* @section: * @section:
* version * library_setup
*
* @title:
* FreeType Version
*
* @abstract:
* Functions and macros related to FreeType versions.
*
* @description:
* Note that those functions and macros are of limited use because even a
* new release of FreeType with only documentation changes increases the
* version number.
*
* @order:
* FT_Library_Version
*
* FREETYPE_MAJOR
* FREETYPE_MINOR
* FREETYPE_PATCH
*
* FT_Face_CheckTrueTypePatents
* FT_Face_SetUnpatentedHinting
* *
*/ */
/************************************************************************** /**************************************************************************
* *
* @enum: * @enum:
@ -4992,6 +5260,13 @@ FT_BEGIN_HEADER
FT_Int *apatch ); FT_Int *apatch );
/**************************************************************************
*
* @section:
* other_api_data
*
*/
/************************************************************************** /**************************************************************************
* *
* @function: * @function:

23
include/freetype/ftchapters.h
View File

@ -31,9 +31,28 @@
* Core API * Core API
* *
* @sections: * @sections:
* version
* basic_types * basic_types
* base_interface * library_setup
* face_creation
* font_testing_macros
* sizing_and_scaling
* glyph_retrieval
* character_mapping
* information_retrieval
* other_api_data
*
*/
/**************************************************************************
*
* @chapter:
* extended_api
*
* @title:
* Extended API
*
* @sections:
* glyph_variants * glyph_variants
* color_management * color_management
* layer_management * layer_management