mirrors/freetype
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

API documentation: Re-organize chapters and sections

Browse Source 
* 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 36a086b630
commit 77bbfc5960
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:
* base_interface
* font_testing_macros
*
* @title:
* Base Interface
* Font Testing Macros
*
* @abstract:
* The FreeType~2 base font interface.
* Macros to test various properties of fonts.
*
* @description:
* This section describes the most important public high-level API
* functions of FreeType~2.
* Macros to test the most important font properties.
*
* It is recommended to use these high-level macros instead of directly
* testing the corresponding flags, which are scattered over various
* structures.
*
* @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_VERTICAL
* FT_HAS_KERNING
@ -176,21 +140,59 @@ FT_BEGIN_HEADER
* FT_IS_NAMED_INSTANCE
* FT_IS_VARIATION
*
* FT_STYLE_FLAG_BOLD
* FT_STYLE_FLAG_ITALIC
*/
/**************************************************************************
*
* FT_SizeRec
* FT_Size_Metrics
* @section:
* library_setup
*
* FT_GlyphSlotRec
* FT_Glyph_Metrics
* FT_SubGlyph
* @title:
* Library Setup
*
* 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_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_Done_Face
* FT_Reference_Face
@ -198,10 +200,36 @@ FT_BEGIN_HEADER
* FT_Face_Properties
* FT_Open_Face
* FT_Open_Args
* FT_OPEN_XXX
* FT_Parameter
* FT_Attach_File
* 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_Pixel_Sizes
* FT_Request_Size
@ -209,44 +237,37 @@ FT_BEGIN_HEADER
* FT_Size_Request_Type
* FT_Size_RequestRec
* FT_Size_Request
*
* FT_Set_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_Get_Char_Index
* 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_XXX
* FT_LOAD_TARGET_MODE
* FT_LOAD_TARGET_XXX
*
* FT_Render_Glyph
* FT_Render_Mode
@ -254,34 +275,121 @@ FT_BEGIN_HEADER
* FT_Kerning_Mode
* 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_Encoding
* FT_ENC_TAG
*
* FT_Select_Charmap
* FT_Set_Charmap
* 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_Glyph_Name
* FT_Get_Postscript_Name
* FT_Get_FSType_Flags
* FT_FSTYPE_XXX
* 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_Size_Internal
* FT_Slot_Internal
*
* FT_FACE_FLAG_XXX
* FT_STYLE_FLAG_XXX
* FT_OPEN_XXX
* FT_LOAD_XXX
* FT_LOAD_TARGET_XXX
* FT_SUBGLYPH_FLAG_XXX
* FT_FSTYPE_XXX
* FT_SubGlyph
*
* FT_HAS_FAST_GLYPHS
* FT_Face_CheckTrueTypePatents
* FT_Face_SetUnpatentedHinting
*
*/
/*************************************************************************/
/*************************************************************************/
/* */
/* B A S I C T Y P E S */
/* */
/*************************************************************************/
/*************************************************************************/
/**************************************************************************
*
* @section:
* glyph_retrieval
*
*/
/**************************************************************************
*
* @struct:
@ -349,6 +457,13 @@ FT_BEGIN_HEADER
} FT_Glyph_Metrics;
/**************************************************************************
*
* @section:
* sizing_and_scaling
*
*/
/**************************************************************************
*
* @struct:
@ -409,6 +524,13 @@ FT_BEGIN_HEADER
/*************************************************************************/
/*************************************************************************/
/**************************************************************************
*
* @section:
* library_setup
*
*/
/**************************************************************************
*
* @type:
@ -483,7 +605,7 @@ FT_BEGIN_HEADER
/**************************************************************************
*
* @section:
* base_interface
* face_creation
*
*/
@ -519,6 +641,13 @@ FT_BEGIN_HEADER
typedef struct FT_FaceRec_* FT_Face;
/**************************************************************************
*
* @section:
* sizing_and_scaling
*
*/
/**************************************************************************
*
* @type:
@ -551,6 +680,13 @@ FT_BEGIN_HEADER
typedef struct FT_SizeRec_* FT_Size;
/**************************************************************************
*
* @section:
* glyph_retrieval
*
*/
/**************************************************************************
*
* @type:
@ -570,6 +706,13 @@ FT_BEGIN_HEADER
typedef struct FT_GlyphSlotRec_* FT_GlyphSlot;
/**************************************************************************
*
* @section:
* character_mapping
*
*/
/**************************************************************************
*
* @type:
@ -877,6 +1020,13 @@ FT_BEGIN_HEADER
/*************************************************************************/
/**************************************************************************
*
* @section:
* other_api_data
*
*/
/**************************************************************************
*
* @type:
@ -892,6 +1042,13 @@ FT_BEGIN_HEADER
typedef struct FT_Face_InternalRec_* FT_Face_Internal;
/**************************************************************************
*
* @section:
* face_creation
*
*/
/**************************************************************************
*
* @struct:
@ -1270,6 +1427,13 @@ FT_BEGIN_HEADER
#define FT_FACE_FLAG_SBIX_OVERLAY ( 1L << 18 )
/**************************************************************************
*
* @section:
* font_testing_macros
*
*/
/**************************************************************************
*
* @macro:
@ -1379,6 +1543,13 @@ FT_BEGIN_HEADER
( !!( (face)->face_flags & FT_FACE_FLAG_FIXED_SIZES ) )
/**************************************************************************
*
* @section:
* other_api_data
*
*/
/**************************************************************************
*
* @macro:
@ -1391,6 +1562,13 @@ FT_BEGIN_HEADER
#define FT_HAS_FAST_GLYPHS( face ) 0
/**************************************************************************
*
* @section:
* font_testing_macros
*
*/
/**************************************************************************
*
* @macro:
@ -1626,6 +1804,13 @@ FT_BEGIN_HEADER
( !!( (face)->face_flags & FT_FACE_FLAG_SBIX_OVERLAY ) )
/**************************************************************************
*
* @section:
* face_creation
*
*/
/**************************************************************************
*
* @enum:
@ -1652,6 +1837,13 @@ FT_BEGIN_HEADER
#define FT_STYLE_FLAG_BOLD ( 1 << 1 )
/**************************************************************************
*
* @section:
* other_api_data
*
*/
/**************************************************************************
*
* @type:
@ -1664,6 +1856,13 @@ FT_BEGIN_HEADER
typedef struct FT_Size_InternalRec_* FT_Size_Internal;
/**************************************************************************
*
* @section:
* sizing_and_scaling
*
*/
/**************************************************************************
*
* @struct:
@ -1815,6 +2014,13 @@ FT_BEGIN_HEADER
} FT_SizeRec;
/**************************************************************************
*
* @section:
* other_api_data
*
*/
/**************************************************************************
*
* @struct:
@ -1846,6 +2052,13 @@ FT_BEGIN_HEADER
typedef struct FT_Slot_InternalRec_* FT_Slot_Internal;
/**************************************************************************
*
* @section:
* glyph_retrieval
*
*/
/**************************************************************************
*
* @struct:
@ -2090,6 +2303,13 @@ FT_BEGIN_HEADER
/*************************************************************************/
/**************************************************************************
*
* @section:
* library_setup
*
*/
/**************************************************************************
*
* @function:
@ -2147,6 +2367,13 @@ FT_BEGIN_HEADER
FT_Done_FreeType( FT_Library library );
/**************************************************************************
*
* @section:
* face_creation
*
*/
/**************************************************************************
*
* @enum:
@ -2648,6 +2875,13 @@ FT_BEGIN_HEADER
FT_Done_Face( FT_Face face );
/**************************************************************************
*
* @section:
* sizing_and_scaling
*
*/
/**************************************************************************
*
* @function:
@ -2940,6 +3174,13 @@ FT_BEGIN_HEADER
FT_UInt pixel_height );
/**************************************************************************
*
* @section:
* glyph_retrieval
*
*/
/**************************************************************************
*
* @function:
@ -2988,6 +3229,13 @@ FT_BEGIN_HEADER
FT_Int32 load_flags );
/**************************************************************************
*
* @section:
* character_mapping
*
*/
/**************************************************************************
*
* @function:
@ -3031,6 +3279,13 @@ FT_BEGIN_HEADER
FT_Int32 load_flags );
/**************************************************************************
*
* @section:
* glyph_retrieval
*
*/
/**************************************************************************
*
* @enum:
@ -3370,6 +3625,13 @@ FT_BEGIN_HEADER
FT_STATIC_CAST( FT_Render_Mode, ( (x) >> 16 ) & 15 )
/**************************************************************************
*
* @section:
* sizing_and_scaling
*
*/
/**************************************************************************
*
* @function:
@ -3445,6 +3707,13 @@ FT_BEGIN_HEADER
FT_Vector* delta );
/**************************************************************************
*
* @section:
* glyph_retrieval
*
*/
/**************************************************************************
*
* @enum:
@ -3839,6 +4108,13 @@ FT_BEGIN_HEADER
FT_Fixed* akerning );
/**************************************************************************
*
* @section:
* character_mapping
*
*/
/**************************************************************************
*
* @function:
@ -4055,6 +4331,13 @@ FT_BEGIN_HEADER
FT_UInt *agindex );
/**************************************************************************
*
* @section:
* face_creation
*
*/
/**************************************************************************
*
* @function:
@ -4153,6 +4436,13 @@ FT_BEGIN_HEADER
FT_Parameter* properties );
/**************************************************************************
*
* @section:
* information_retrieval
*
*/
/**************************************************************************
*
* @function:
@ -4899,32 +5189,10 @@ FT_BEGIN_HEADER
/**************************************************************************
*
* @section:
* version
*
* @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
* library_setup
*
*/
/**************************************************************************
*
* @enum:
@ -4991,6 +5259,13 @@ FT_BEGIN_HEADER
FT_Int *apatch );
/**************************************************************************
*
* @section:
* other_api_data
*
*/
/**************************************************************************
*
* @function:

23
include/freetype/ftchapters.h
View File

@ -31,9 +31,28 @@
* Core API
*
* @sections:
* version
* 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
* color_management
* layer_management