freetype2/freetype/ftsnames.h

0001 /****************************************************************************
0002  *
0003  * ftsnames.h
0004  *
0005  *   Simple interface to access SFNT 'name' tables (which are used
0006  *   to hold font names, copyright info, notices, etc.) (specification).
0007  *
0008  *   This is _not_ used to retrieve glyph names!
0009  *
0010  * Copyright (C) 1996-2023 by
0011  * David Turner, Robert Wilhelm, and Werner Lemberg.
0012  *
0013  * This file is part of the FreeType project, and may only be used,
0014  * modified, and distributed under the terms of the FreeType project
0015  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0016  * this file you indicate that you have read the license and
0017  * understand and accept it fully.
0018  *
0019  */
0020
0021
0022 #ifndef FTSNAMES_H_
0023 #define FTSNAMES_H_
0024
0025
0026 #include <freetype/freetype.h>
0027 #include <freetype/ftparams.h>
0028
0029 #ifdef FREETYPE_H
0030 #error "freetype.h of FreeType 1 has been loaded!"
0031 #error "Please fix the directory search order for header files"
0032 #error "so that freetype.h of FreeType 2 is found first."
0033 #endif
0034
0035
0036 FT_BEGIN_HEADER
0037
0038
0039   /**************************************************************************
0040    *
0041    * @section:
0042    *   sfnt_names
0043    *
0044    * @title:
0045    *   SFNT Names
0046    *
0047    * @abstract:
0048    *   Access the names embedded in TrueType and OpenType files.
0049    *
0050    * @description:
0051    *   The TrueType and OpenType specifications allow the inclusion of a
0052    *   special names table ('name') in font files.  This table contains
0053    *   textual (and internationalized) information regarding the font, like
0054    *   family name, copyright, version, etc.
0055    *
0056    *   The definitions below are used to access them if available.
0057    *
0058    *   Note that this has nothing to do with glyph names!
0059    *
0060    */
0061
0062
0063   /**************************************************************************
0064    *
0065    * @struct:
0066    *   FT_SfntName
0067    *
0068    * @description:
0069    *   A structure used to model an SFNT 'name' table entry.
0070    *
0071    * @fields:
0072    *   platform_id ::
0073    *     The platform ID for `string`.  See @TT_PLATFORM_XXX for possible
0074    *     values.
0075    *
0076    *   encoding_id ::
0077    *     The encoding ID for `string`.  See @TT_APPLE_ID_XXX, @TT_MAC_ID_XXX,
0078    *     @TT_ISO_ID_XXX, @TT_MS_ID_XXX, and @TT_ADOBE_ID_XXX for possible
0079    *     values.
0080    *
0081    *   language_id ::
0082    *     The language ID for `string`.  See @TT_MAC_LANGID_XXX and
0083    *     @TT_MS_LANGID_XXX for possible values.
0084    *
0085    *     Registered OpenType values for `language_id` are always smaller than
0086    *     0x8000; values equal or larger than 0x8000 usually indicate a
0087    *     language tag string (introduced in OpenType version 1.6).  Use
0088    *     function @FT_Get_Sfnt_LangTag with `language_id` as its argument to
0089    *     retrieve the associated language tag.
0090    *
0091    *   name_id ::
0092    *     An identifier for `string`.  See @TT_NAME_ID_XXX for possible
0093    *     values.
0094    *
0095    *   string ::
0096    *     The 'name' string.  Note that its format differs depending on the
0097    *     (platform,encoding) pair, being either a string of bytes (without a
0098    *     terminating `NULL` byte) or containing UTF-16BE entities.
0099    *
0100    *   string_len ::
0101    *     The length of `string` in bytes.
0102    *
0103    * @note:
0104    *   Please refer to the TrueType or OpenType specification for more
0105    *   details.
0106    */
0107   typedef struct  FT_SfntName_
0108   {
0109     FT_UShort  platform_id;
0110     FT_UShort  encoding_id;
0111     FT_UShort  language_id;
0112     FT_UShort  name_id;
0113
0114     FT_Byte*   string;      /* this string is *not* null-terminated! */
0115     FT_UInt    string_len;  /* in bytes                              */
0116
0117   } FT_SfntName;
0118
0119
0120   /**************************************************************************
0121    *
0122    * @function:
0123    *   FT_Get_Sfnt_Name_Count
0124    *
0125    * @description:
0126    *   Retrieve the number of name strings in the SFNT 'name' table.
0127    *
0128    * @input:
0129    *   face ::
0130    *     A handle to the source face.
0131    *
0132    * @return:
0133    *   The number of strings in the 'name' table.
0134    *
0135    * @note:
0136    *   This function always returns an error if the config macro
0137    *   `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`.
0138    */
0139   FT_EXPORT( FT_UInt )
0140   FT_Get_Sfnt_Name_Count( FT_Face  face );
0141
0142
0143   /**************************************************************************
0144    *
0145    * @function:
0146    *   FT_Get_Sfnt_Name
0147    *
0148    * @description:
0149    *   Retrieve a string of the SFNT 'name' table for a given index.
0150    *
0151    * @input:
0152    *   face ::
0153    *     A handle to the source face.
0154    *
0155    *   idx ::
0156    *     The index of the 'name' string.
0157    *
0158    * @output:
0159    *   aname ::
0160    *     The indexed @FT_SfntName structure.
0161    *
0162    * @return:
0163    *   FreeType error code.  0~means success.
0164    *
0165    * @note:
0166    *   The `string` array returned in the `aname` structure is not
0167    *   null-terminated.  Note that you don't have to deallocate `string` by
0168    *   yourself; FreeType takes care of it if you call @FT_Done_Face.
0169    *
0170    *   Use @FT_Get_Sfnt_Name_Count to get the total number of available
0171    *   'name' table entries, then do a loop until you get the right platform,
0172    *   encoding, and name ID.
0173    *
0174    *   'name' table format~1 entries can use language tags also, see
0175    *   @FT_Get_Sfnt_LangTag.
0176    *
0177    *   This function always returns an error if the config macro
0178    *   `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`.
0179    */
0180   FT_EXPORT( FT_Error )
0181   FT_Get_Sfnt_Name( FT_Face       face,
0182                     FT_UInt       idx,
0183                     FT_SfntName  *aname );
0184
0185
0186   /**************************************************************************
0187    *
0188    * @struct:
0189    *   FT_SfntLangTag
0190    *
0191    * @description:
0192    *   A structure to model a language tag entry from an SFNT 'name' table.
0193    *
0194    * @fields:
0195    *   string ::
0196    *     The language tag string, encoded in UTF-16BE (without trailing
0197    *     `NULL` bytes).
0198    *
0199    *   string_len ::
0200    *     The length of `string` in **bytes**.
0201    *
0202    * @note:
0203    *   Please refer to the TrueType or OpenType specification for more
0204    *   details.
0205    *
0206    * @since:
0207    *   2.8
0208    */
0209   typedef struct  FT_SfntLangTag_
0210   {
0211     FT_Byte*  string;      /* this string is *not* null-terminated! */
0212     FT_UInt   string_len;  /* in bytes                              */
0213
0214   } FT_SfntLangTag;
0215
0216
0217   /**************************************************************************
0218    *
0219    * @function:
0220    *   FT_Get_Sfnt_LangTag
0221    *
0222    * @description:
0223    *   Retrieve the language tag associated with a language ID of an SFNT
0224    *   'name' table entry.
0225    *
0226    * @input:
0227    *   face ::
0228    *     A handle to the source face.
0229    *
0230    *   langID ::
0231    *     The language ID, as returned by @FT_Get_Sfnt_Name.  This is always a
0232    *     value larger than 0x8000.
0233    *
0234    * @output:
0235    *   alangTag ::
0236    *     The language tag associated with the 'name' table entry's language
0237    *     ID.
0238    *
0239    * @return:
0240    *   FreeType error code.  0~means success.
0241    *
0242    * @note:
0243    *   The `string` array returned in the `alangTag` structure is not
0244    *   null-terminated.  Note that you don't have to deallocate `string` by
0245    *   yourself; FreeType takes care of it if you call @FT_Done_Face.
0246    *
0247    *   Only 'name' table format~1 supports language tags.  For format~0
0248    *   tables, this function always returns FT_Err_Invalid_Table.  For
0249    *   invalid format~1 language ID values, FT_Err_Invalid_Argument is
0250    *   returned.
0251    *
0252    *   This function always returns an error if the config macro
0253    *   `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`.
0254    *
0255    * @since:
0256    *   2.8
0257    */
0258   FT_EXPORT( FT_Error )
0259   FT_Get_Sfnt_LangTag( FT_Face          face,
0260                        FT_UInt          langID,
0261                        FT_SfntLangTag  *alangTag );
0262
0263
0264   /* */
0265
0266
0267 FT_END_HEADER
0268
0269 #endif /* FTSNAMES_H_ */
0270
0271
0272 /* END */