ref: 757bdf1aef3d93a27968857ac5b4435a52fa24a0
dir: /include/freetype/ftsnames.h/
/****************************************************************************
*
* ftsnames.h
*
* Simple interface to access SFNT `name' tables (which are used
* to hold font names, copyright info, notices, etc.) (specification).
*
* This is _not_ used to retrieve glyph names!
*
* Copyright 1996-2018 by
* David Turner, Robert Wilhelm, and Werner Lemberg.
*
* This file is part of the FreeType project, and may only be used,
* modified, and distributed under the terms of the FreeType project
* license, LICENSE.TXT. By continuing to use, modify, or distribute
* this file you indicate that you have read the license and
* understand and accept it fully.
*
*/
#ifndef FTSNAMES_H_
#define FTSNAMES_H_
#include <ft2build.h>
#include FT_FREETYPE_H
#include FT_PARAMETER_TAGS_H
#ifdef FREETYPE_H
#error "freetype.h of FreeType 1 has been loaded!"
#error "Please fix the directory search order for header files"
#error "so that freetype.h of FreeType 2 is found first."
#endif
FT_BEGIN_HEADER
/**************************************************************************
*
* @section:
* sfnt_names
*
* @title:
* SFNT Names
*
* @abstract:
* Access the names embedded in TrueType and OpenType files.
*
* @description:
* The TrueType and OpenType specifications allow the inclusion of
* a special names table (`name') in font files. This table contains
* textual (and internationalized) information regarding the font,
* like family name, copyright, version, etc.
*
* The definitions below are used to access them if available.
*
* Note that this has nothing to do with glyph names!
*
*/
/**************************************************************************
*
* @struct:
* FT_SfntName
*
* @description:
* A structure used to model an SFNT `name' table entry.
*
* @fields:
* platform_id ::
* The platform ID for `string'.
* See @TT_PLATFORM_XXX for possible values.
*
* encoding_id ::
* The encoding ID for `string'.
* See @TT_APPLE_ID_XXX, @TT_MAC_ID_XXX,
* @TT_ISO_ID_XXX, @TT_MS_ID_XXX, and @TT_ADOBE_ID_XXX
* for possible values.
*
* language_id ::
* The language ID for `string'.
* See @TT_MAC_LANGID_XXX and @TT_MS_LANGID_XXX for
* possible values.
*
* Registered OpenType values for `language_id' are
* always smaller than 0x8000; values equal or larger
* than 0x8000 usually indicate a language tag string
* (introduced in OpenType version 1.6). Use function
* @FT_Get_Sfnt_LangTag with `language_id' as its
* argument to retrieve the associated language tag.
*
* name_id ::
* An identifier for `string'.
* See @TT_NAME_ID_XXX for possible values.
*
* string ::
* The `name' string. Note that its format differs
* depending on the (platform,encoding) pair, being
* either a string of bytes (without a terminating
* NULL byte) or containing UTF-16BE entities.
*
* string_len ::
* The length of `string' in bytes.
*
* @note:
* Please refer to the TrueType or OpenType specification for more
* details.
*/
typedef struct FT_SfntName_
{
FT_UShort platform_id;
FT_UShort encoding_id;
FT_UShort language_id;
FT_UShort name_id;
FT_Byte* string; /* this string is *not* null-terminated! */
FT_UInt string_len; /* in bytes */
} FT_SfntName;
/**************************************************************************
*
* @function:
* FT_Get_Sfnt_Name_Count
*
* @description:
* Retrieve the number of name strings in the SFNT `name' table.
*
* @input:
* face ::
* A handle to the source face.
*
* @return:
* The number of strings in the `name' table.
*
* @note:
* This function always returns an error if the config macro
* `TT_CONFIG_OPTION_SFNT_NAMES' is not defined in `ftoption.h'.
*/
FT_EXPORT( FT_UInt )
FT_Get_Sfnt_Name_Count( FT_Face face );
/**************************************************************************
*
* @function:
* FT_Get_Sfnt_Name
*
* @description:
* Retrieve a string of the SFNT `name' table for a given index.
*
* @input:
* face ::
* A handle to the source face.
*
* idx ::
* The index of the `name' string.
*
* @output:
* aname ::
* The indexed @FT_SfntName structure.
*
* @return:
* FreeType error code. 0~means success.
*
* @note:
* The `string' array returned in the `aname' structure is not
* null-terminated. Note that you don't have to deallocate `string'
* by yourself; FreeType takes care of it if you call @FT_Done_Face.
*
* Use @FT_Get_Sfnt_Name_Count to get the total number of available
* `name' table entries, then do a loop until you get the right
* platform, encoding, and name ID.
*
* `name' table format~1 entries can use language tags also, see
* @FT_Get_Sfnt_LangTag.
*
* This function always returns an error if the config macro
* `TT_CONFIG_OPTION_SFNT_NAMES' is not defined in `ftoption.h'.
*/
FT_EXPORT( FT_Error )
FT_Get_Sfnt_Name( FT_Face face,
FT_UInt idx,
FT_SfntName *aname );
/**************************************************************************
*
* @struct:
* FT_SfntLangTag
*
* @description:
* A structure to model a language tag entry from an SFNT `name'
* table.
*
* @fields:
* string ::
* The language tag string, encoded in UTF-16BE
* (without trailing NULL bytes).
*
* string_len ::
* The length of `string' in *bytes*.
*
* @note:
* Please refer to the TrueType or OpenType specification for more
* details.
*
* @since:
* 2.8
*/
typedef struct FT_SfntLangTag_
{
FT_Byte* string; /* this string is *not* null-terminated! */
FT_UInt string_len; /* in bytes */
} FT_SfntLangTag;
/**************************************************************************
*
* @function:
* FT_Get_Sfnt_LangTag
*
* @description:
* Retrieve the language tag associated with a language ID of an SFNT
* `name' table entry.
*
* @input:
* face ::
* A handle to the source face.
*
* langID ::
* The language ID, as returned by @FT_Get_Sfnt_Name.
* This is always a value larger than 0x8000.
*
* @output:
* alangTag ::
* The language tag associated with the `name' table
* entry's language ID.
*
* @return:
* FreeType error code. 0~means success.
*
* @note:
* The `string' array returned in the `alangTag' structure is not
* null-terminated. Note that you don't have to deallocate `string'
* by yourself; FreeType takes care of it if you call @FT_Done_Face.
*
* Only `name' table format~1 supports language tags. For format~0
* tables, this function always returns FT_Err_Invalid_Table. For
* invalid format~1 language ID values, FT_Err_Invalid_Argument is
* returned.
*
* This function always returns an error if the config macro
* `TT_CONFIG_OPTION_SFNT_NAMES' is not defined in `ftoption.h'.
*
* @since:
* 2.8
*/
FT_EXPORT( FT_Error )
FT_Get_Sfnt_LangTag( FT_Face face,
FT_UInt langID,
FT_SfntLangTag *alangTag );
/* */
FT_END_HEADER
#endif /* FTSNAMES_H_ */
/* END */