sdk/lib/3rdparty/freetype/include/freetype/ftsnames.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftsnames.h                                                             */
   4 /*                                                                         */
   5 /*    Simple interface to access SFNT `name' tables (which are used        */
   6 /*    to hold font names, copyright info, notices, etc.) (specification).  */
   7 /*                                                                         */
   8 /*    This is _not_ used to retrieve glyph names!                          */
   9 /*                                                                         */
  10 /*  Copyright 1996-2018 by                                                 */
  11 /*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
  12 /*                                                                         */
  13 /*  This file is part of the FreeType project, and may only be used,       */
  14 /*  modified, and distributed under the terms of the FreeType project      */
  15 /*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
  16 /*  this file you indicate that you have read the license and              */
  17 /*  understand and accept it fully.                                        */
  18 /*                                                                         */
  19 /***************************************************************************/
  20
  21
  22 #ifndef FTSNAMES_H_
  23 #define FTSNAMES_H_
  24
  25
  26 #include <ft2build.h>
  27 #include FT_FREETYPE_H
  28 #include FT_PARAMETER_TAGS_H
  29
  30 #ifdef FREETYPE_H
  31 #error "freetype.h of FreeType 1 has been loaded!"
  32 #error "Please fix the directory search order for header files"
  33 #error "so that freetype.h of FreeType 2 is found first."
  34 #endif
  35
  36
  37 FT_BEGIN_HEADER
  38
  39
  40   /*************************************************************************/
  41   /*                                                                       */
  42   /* <Section>                                                             */
  43   /*    sfnt_names                                                         */
  44   /*                                                                       */
  45   /* <Title>                                                               */
  46   /*    SFNT Names                                                         */
  47   /*                                                                       */
  48   /* <Abstract>                                                            */
  49   /*    Access the names embedded in TrueType and OpenType files.          */
  50   /*                                                                       */
  51   /* <Description>                                                         */
  52   /*    The TrueType and OpenType specifications allow the inclusion of    */
  53   /*    a special names table (`name') in font files.  This table contains */
  54   /*    textual (and internationalized) information regarding the font,    */
  55   /*    like family name, copyright, version, etc.                         */
  56   /*                                                                       */
  57   /*    The definitions below are used to access them if available.        */
  58   /*                                                                       */
  59   /*    Note that this has nothing to do with glyph names!                 */
  60   /*                                                                       */
  61   /*************************************************************************/
  62
  63
  64   /*************************************************************************/
  65   /*                                                                       */
  66   /* <Struct>                                                              */
  67   /*    FT_SfntName                                                        */
  68   /*                                                                       */
  69   /* <Description>                                                         */
  70   /*    A structure used to model an SFNT `name' table entry.              */
  71   /*                                                                       */
  72   /* <Fields>                                                              */
  73   /*    platform_id :: The platform ID for `string'.                       */
  74   /*                   See @TT_PLATFORM_XXX for possible values.           */
  75   /*                                                                       */
  76   /*    encoding_id :: The encoding ID for `string'.                       */
  77   /*                   See @TT_APPLE_ID_XXX, @TT_MAC_ID_XXX,               */
  78   /*                   @TT_ISO_ID_XXX, @TT_MS_ID_XXX, and @TT_ADOBE_ID_XXX */
  79   /*                   for possible values.                                */
  80   /*                                                                       */
  81   /*    language_id :: The language ID for `string'.                       */
  82   /*                   See @TT_MAC_LANGID_XXX and @TT_MS_LANGID_XXX for    */
  83   /*                   possible values.                                    */
  84   /*                                                                       */
  85   /*                   Registered OpenType values for `language_id' are    */
  86   /*                   always smaller than 0x8000; values equal or larger  */
  87   /*                   than 0x8000 usually indicate a language tag string  */
  88   /*                   (introduced in OpenType version 1.6).  Use function */
  89   /*                   @FT_Get_Sfnt_LangTag with `language_id' as its      */
  90   /*                   argument to retrieve the associated language tag.   */
  91   /*                                                                       */
  92   /*    name_id     :: An identifier for `string'.                         */
  93   /*                   See @TT_NAME_ID_XXX for possible values.            */
  94   /*                                                                       */
  95   /*    string      :: The `name' string.  Note that its format differs    */
  96   /*                   depending on the (platform,encoding) pair, being    */
  97   /*                   either a string of bytes (without a terminating     */
  98   /*                   NULL byte) or containing UTF-16BE entities.         */
  99   /*                                                                       */
 100   /*    string_len  :: The length of `string' in bytes.                    */
 101   /*                                                                       */
 102   /* <Note>                                                                */
 103   /*    Please refer to the TrueType or OpenType specification for more    */
 104   /*    details.                                                           */
 105   /*                                                                       */
 106   typedef struct  FT_SfntName_
 107   {
 108     FT_UShort  platform_id;
 109     FT_UShort  encoding_id;
 110     FT_UShort  language_id;
 111     FT_UShort  name_id;
 112
 113     FT_Byte*   string;      /* this string is *not* null-terminated! */
 114     FT_UInt    string_len;  /* in bytes                              */
 115
 116   } FT_SfntName;
 117
 118
 119   /*************************************************************************/
 120   /*                                                                       */
 121   /* <Function>                                                            */
 122   /*    FT_Get_Sfnt_Name_Count                                             */
 123   /*                                                                       */
 124   /* <Description>                                                         */
 125   /*    Retrieve the number of name strings in the SFNT `name' table.      */
 126   /*                                                                       */
 127   /* <Input>                                                               */
 128   /*    face :: A handle to the source face.                               */
 129   /*                                                                       */
 130   /* <Return>                                                              */
 131   /*    The number of strings in the `name' table.                         */
 132   /*                                                                       */
 133   FT_EXPORT( FT_UInt )
 134   FT_Get_Sfnt_Name_Count( FT_Face  face );
 135
 136
 137   /*************************************************************************/
 138   /*                                                                       */
 139   /* <Function>                                                            */
 140   /*    FT_Get_Sfnt_Name                                                   */
 141   /*                                                                       */
 142   /* <Description>                                                         */
 143   /*    Retrieve a string of the SFNT `name' table for a given index.      */
 144   /*                                                                       */
 145   /* <Input>                                                               */
 146   /*    face  :: A handle to the source face.                              */
 147   /*                                                                       */
 148   /*    idx   :: The index of the `name' string.                           */
 149   /*                                                                       */
 150   /* <Output>                                                              */
 151   /*    aname :: The indexed @FT_SfntName structure.                       */
 152   /*                                                                       */
 153   /* <Return>                                                              */
 154   /*    FreeType error code.  0~means success.                             */
 155   /*                                                                       */
 156   /* <Note>                                                                */
 157   /*    The `string' array returned in the `aname' structure is not        */
 158   /*    null-terminated.  Note that you don't have to deallocate `string'  */
 159   /*    by yourself; FreeType takes care of it if you call @FT_Done_Face.  */
 160   /*                                                                       */
 161   /*    Use @FT_Get_Sfnt_Name_Count to get the total number of available   */
 162   /*    `name' table entries, then do a loop until you get the right       */
 163   /*    platform, encoding, and name ID.                                   */
 164   /*                                                                       */
 165   /*    `name' table format~1 entries can use language tags also, see      */
 166   /*    @FT_Get_Sfnt_LangTag.                                              */
 167   /*                                                                       */
 168   FT_EXPORT( FT_Error )
 169   FT_Get_Sfnt_Name( FT_Face       face,
 170                     FT_UInt       idx,
 171                     FT_SfntName  *aname );
 172
 173
 174   /*************************************************************************/
 175   /*                                                                       */
 176   /* <Struct>                                                              */
 177   /*    FT_SfntLangTag                                                     */
 178   /*                                                                       */
 179   /* <Description>                                                         */
 180   /*    A structure to model a language tag entry from an SFNT `name'      */
 181   /*    table.                                                             */
 182   /*                                                                       */
 183   /* <Fields>                                                              */
 184   /*    string      :: The language tag string, encoded in UTF-16BE        */
 185   /*                   (without trailing NULL bytes).                      */
 186   /*                                                                       */
 187   /*    string_len  :: The length of `string' in *bytes*.                  */
 188   /*                                                                       */
 189   /* <Note>                                                                */
 190   /*    Please refer to the TrueType or OpenType specification for more    */
 191   /*    details.                                                           */
 192   /*                                                                       */
 193   /* <Since>                                                               */
 194   /*    2.8                                                                */
 195   /*                                                                       */
 196   typedef struct  FT_SfntLangTag_
 197   {
 198     FT_Byte*  string;      /* this string is *not* null-terminated! */
 199     FT_UInt   string_len;  /* in bytes                              */
 200
 201   } FT_SfntLangTag;
 202
 203
 204   /*************************************************************************/
 205   /*                                                                       */
 206   /* <Function>                                                            */
 207   /*    FT_Get_Sfnt_LangTag                                                */
 208   /*                                                                       */
 209   /* <Description>                                                         */
 210   /*    Retrieve the language tag associated with a language ID of an SFNT */
 211   /*    `name' table entry.                                                */
 212   /*                                                                       */
 213   /* <Input>                                                               */
 214   /*    face     :: A handle to the source face.                           */
 215   /*                                                                       */
 216   /*    langID   :: The language ID, as returned by @FT_Get_Sfnt_Name.     */
 217   /*                This is always a value larger than 0x8000.             */
 218   /*                                                                       */
 219   /* <Output>                                                              */
 220   /*    alangTag :: The language tag associated with the `name' table      */
 221   /*                entry's language ID.                                   */
 222   /*                                                                       */
 223   /* <Return>                                                              */
 224   /*    FreeType error code.  0~means success.                             */
 225   /*                                                                       */
 226   /* <Note>                                                                */
 227   /*    The `string' array returned in the `alangTag' structure is not     */
 228   /*    null-terminated.  Note that you don't have to deallocate `string'  */
 229   /*    by yourself; FreeType takes care of it if you call @FT_Done_Face.  */
 230   /*                                                                       */
 231   /*    Only `name' table format~1 supports language tags.  For format~0   */
 232   /*    tables, this function always returns FT_Err_Invalid_Table.  For    */
 233   /*    invalid format~1 language ID values, FT_Err_Invalid_Argument is    */
 234   /*    returned.                                                          */
 235   /*                                                                       */
 236   /* <Since>                                                               */
 237   /*    2.8                                                                */
 238   /*                                                                       */
 239   FT_EXPORT( FT_Error )
 240   FT_Get_Sfnt_LangTag( FT_Face          face,
 241                        FT_UInt          langID,
 242                        FT_SfntLangTag  *alangTag );
 243
 244
 245   /* */
 246
 247
 248 FT_END_HEADER
 249
 250 #endif /* FTSNAMES_H_ */
 251
 252
 253 /* END */