From 15f687349528fb0d7cba1ee7a8becf0af29116ec Mon Sep 17 00:00:00 2001 From: Alexei Podtelezhnikov Date: Tue, 4 Oct 2022 23:36:09 -0400 Subject: [PATCH] Improve FT_Get_Name_Index docs and place it next to FT_Get_Glyph_Name. --- include/freetype/freetype.h | 190 ++++++++++++++++++------------------ 1 file changed, 96 insertions(+), 94 deletions(-) diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h index 44d1b1acc..18f3c13d4 100644 --- a/include/freetype/freetype.h +++ b/include/freetype/freetype.h @@ -215,7 +215,6 @@ FT_BEGIN_HEADER * FT_Get_Char_Index * FT_Get_First_Char * FT_Get_Next_Char - * FT_Get_Name_Index * FT_Load_Char * * FT_OPEN_MEMORY @@ -254,14 +253,15 @@ FT_BEGIN_HEADER * FT_Get_Kerning * FT_Kerning_Mode * FT_Get_Track_Kerning - * FT_Get_Glyph_Name - * FT_Get_Postscript_Name * * FT_CharMapRec * FT_Select_Charmap * FT_Set_Charmap * FT_Get_Charmap_Index * + * FT_Get_Name_Index + * FT_Get_Glyph_Name + * FT_Get_Postscript_Name * FT_Get_FSType_Flags * FT_Get_SubGlyph_Info * @@ -3840,89 +3840,6 @@ FT_BEGIN_HEADER FT_Fixed* akerning ); - /************************************************************************** - * - * @function: - * FT_Get_Glyph_Name - * - * @description: - * Retrieve the ASCII name of a given glyph in a face. This only works - * for those faces where @FT_HAS_GLYPH_NAMES(face) returns~1. - * - * @input: - * face :: - * A handle to a source face object. - * - * glyph_index :: - * The glyph index. - * - * buffer_max :: - * The maximum number of bytes available in the buffer. - * - * @output: - * buffer :: - * A pointer to a target buffer where the name is copied to. - * - * @return: - * FreeType error code. 0~means success. - * - * @note: - * An error is returned if the face doesn't provide glyph names or if the - * glyph index is invalid. In all cases of failure, the first byte of - * `buffer` is set to~0 to indicate an empty name. - * - * The glyph name is truncated to fit within the buffer if it is too - * long. The returned string is always zero-terminated. - * - * Be aware that FreeType reorders glyph indices internally so that glyph - * index~0 always corresponds to the 'missing glyph' (called '.notdef'). - * - * This function always returns an error if the config macro - * `FT_CONFIG_OPTION_NO_GLYPH_NAMES` is not defined in `ftoption.h`. - */ - FT_EXPORT( FT_Error ) - FT_Get_Glyph_Name( FT_Face face, - FT_UInt glyph_index, - FT_Pointer buffer, - FT_UInt buffer_max ); - - - /************************************************************************** - * - * @function: - * FT_Get_Postscript_Name - * - * @description: - * Retrieve the ASCII PostScript name of a given face, if available. - * This only works with PostScript, TrueType, and OpenType fonts. - * - * @input: - * face :: - * A handle to the source face object. - * - * @return: - * A pointer to the face's PostScript name. `NULL` if unavailable. - * - * @note: - * The returned pointer is owned by the face and is destroyed with it. - * - * For variation fonts, this string changes if you select a different - * instance, and you have to call `FT_Get_PostScript_Name` again to - * retrieve it. FreeType follows Adobe TechNote #5902, 'Generating - * PostScript Names for Fonts Using OpenType Font Variations'. - * - * https://download.macromedia.com/pub/developer/opentype/tech-notes/5902.AdobePSNameGeneration.html - * - * [Since 2.9] Special PostScript names for named instances are only - * returned if the named instance is set with @FT_Set_Named_Instance (and - * the font has corresponding entries in its 'fvar' table). If - * @FT_IS_VARIATION returns true, the algorithmically derived PostScript - * name is provided, not looking up special entries for named instances. - */ - FT_EXPORT( const char* ) - FT_Get_Postscript_Name( FT_Face face ); - - /************************************************************************** * * @function: @@ -4243,7 +4160,8 @@ FT_BEGIN_HEADER * FT_Get_Name_Index * * @description: - * Return the glyph index of a given glyph name. + * Return the glyph index of a given glyph name. This only works + * for those faces where @FT_HAS_GLYPH_NAMES returns true. * * @input: * face :: @@ -4254,12 +4172,103 @@ FT_BEGIN_HEADER * * @return: * The glyph index. 0~means 'undefined character code'. + * + * @note: + * The acceptable glyph name might come from + * [Adobe Glyph List](https://github.com/adobe-type-tools/agl-aglfn). + * See @FT_Get_Glyph_Name for the resiprocal function. + * + * This function always returns~0 if the config macro + * `FT_CONFIG_OPTION_NO_GLYPH_NAMES` is not defined in `ftoption.h`. */ FT_EXPORT( FT_UInt ) FT_Get_Name_Index( FT_Face face, const FT_String* glyph_name ); + /************************************************************************** + * + * @function: + * FT_Get_Glyph_Name + * + * @description: + * Retrieve the ASCII name of a given glyph in a face. This only works + * for those faces where @FT_HAS_GLYPH_NAMES returns true. + * + * @input: + * face :: + * A handle to a source face object. + * + * glyph_index :: + * The glyph index. + * + * buffer_max :: + * The maximum number of bytes available in the buffer. + * + * @output: + * buffer :: + * A pointer to a target buffer where the name is copied to. + * + * @return: + * FreeType error code. 0~means success. + * + * @note: + * An error is returned if the face doesn't provide glyph names or if the + * glyph index is invalid. In all cases of failure, the first byte of + * `buffer` is set to~0 to indicate an empty name. + * + * The glyph name is truncated to fit within the buffer if it is too + * long. The returned string is always zero-terminated. + * + * Be aware that FreeType reorders glyph indices internally so that glyph + * index~0 always corresponds to the 'missing glyph' (called '.notdef'). + * + * This function always returns an error if the config macro + * `FT_CONFIG_OPTION_NO_GLYPH_NAMES` is not defined in `ftoption.h`. + */ + FT_EXPORT( FT_Error ) + FT_Get_Glyph_Name( FT_Face face, + FT_UInt glyph_index, + FT_Pointer buffer, + FT_UInt buffer_max ); + + + /************************************************************************** + * + * @function: + * FT_Get_Postscript_Name + * + * @description: + * Retrieve the ASCII PostScript name of a given face, if available. + * This only works with PostScript, TrueType, and OpenType fonts. + * + * @input: + * face :: + * A handle to the source face object. + * + * @return: + * A pointer to the face's PostScript name. `NULL` if unavailable. + * + * @note: + * The returned pointer is owned by the face and is destroyed with it. + * + * For variation fonts, this string changes if you select a different + * instance, and you have to call `FT_Get_PostScript_Name` again to + * retrieve it. FreeType follows Adobe TechNote #5902, 'Generating + * PostScript Names for Fonts Using OpenType Font Variations'. + * + * https://download.macromedia.com/pub/developer/opentype/tech-notes/5902.AdobePSNameGeneration.html + * + * [Since 2.9] Special PostScript names for named instances are only + * returned if the named instance is set with @FT_Set_Named_Instance (and + * the font has corresponding entries in its 'fvar' table). If + * @FT_IS_VARIATION returns true, the algorithmically derived PostScript + * name is provided, not looking up special entries for named instances. + */ + FT_EXPORT( const char* ) + FT_Get_Postscript_Name( FT_Face face ); + + /************************************************************************** * * @enum: @@ -4346,13 +4355,6 @@ FT_BEGIN_HEADER FT_Matrix *p_transform ); - /************************************************************************** - * - * @section: - * base_interface - * - */ - /************************************************************************** * * @enum: