[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[freetype2] master 15f687349: Improve FT_Get_Name_Index docs and place i
From: |
Werner Lemberg |
Subject: |
[freetype2] master 15f687349: Improve FT_Get_Name_Index docs and place it next to FT_Get_Glyph_Name. |
Date: |
Tue, 4 Oct 2022 23:38:54 -0400 (EDT) |
branch: master
commit 15f687349528fb0d7cba1ee7a8becf0af29116ec
Author: Alexei Podtelezhnikov <apodtele@gmail.com>
Commit: Alexei Podtelezhnikov <apodtele@gmail.com>
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:
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [freetype2] master 15f687349: Improve FT_Get_Name_Index docs and place it next to FT_Get_Glyph_Name.,
Werner Lemberg <=