Home | History | Annotate | Download | only in freetype
      1 /***************************************************************************/
      2 /*                                                                         */
      3 /*  t1tables.h                                                             */
      4 /*                                                                         */
      5 /*    Basic Type 1/Type 2 tables definitions and interface (specification  */
      6 /*    only).                                                               */
      7 /*                                                                         */
      8 /*  Copyright 1996-2004, 2006, 2008, 2009, 2011 by                         */
      9 /*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
     10 /*                                                                         */
     11 /*  This file is part of the FreeType project, and may only be used,       */
     12 /*  modified, and distributed under the terms of the FreeType project      */
     13 /*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
     14 /*  this file you indicate that you have read the license and              */
     15 /*  understand and accept it fully.                                        */
     16 /*                                                                         */
     17 /***************************************************************************/
     18 
     19 
     20 #ifndef __T1TABLES_H__
     21 #define __T1TABLES_H__
     22 
     23 
     24 #include <ft2build.h>
     25 #include FT_FREETYPE_H
     26 
     27 #ifdef FREETYPE_H
     28 #error "freetype.h of FreeType 1 has been loaded!"
     29 #error "Please fix the directory search order for header files"
     30 #error "so that freetype.h of FreeType 2 is found first."
     31 #endif
     32 
     33 
     34 FT_BEGIN_HEADER
     35 
     36 
     37   /*************************************************************************/
     38   /*                                                                       */
     39   /* <Section>                                                             */
     40   /*    type1_tables                                                       */
     41   /*                                                                       */
     42   /* <Title>                                                               */
     43   /*    Type 1 Tables                                                      */
     44   /*                                                                       */
     45   /* <Abstract>                                                            */
     46   /*    Type~1 (PostScript) specific font tables.                          */
     47   /*                                                                       */
     48   /* <Description>                                                         */
     49   /*    This section contains the definition of Type 1-specific tables,    */
     50   /*    including structures related to other PostScript font formats.     */
     51   /*                                                                       */
     52   /*************************************************************************/
     53 
     54 
     55   /* Note that we separate font data in PS_FontInfoRec and PS_PrivateRec */
     56   /* structures in order to support Multiple Master fonts.               */
     57 
     58 
     59   /*************************************************************************/
     60   /*                                                                       */
     61   /* <Struct>                                                              */
     62   /*    PS_FontInfoRec                                                     */
     63   /*                                                                       */
     64   /* <Description>                                                         */
     65   /*    A structure used to model a Type~1 or Type~2 FontInfo dictionary.  */
     66   /*    Note that for Multiple Master fonts, each instance has its own     */
     67   /*    FontInfo dictionary.                                               */
     68   /*                                                                       */
     69   typedef struct  PS_FontInfoRec_
     70   {
     71     FT_String*  version;
     72     FT_String*  notice;
     73     FT_String*  full_name;
     74     FT_String*  family_name;
     75     FT_String*  weight;
     76     FT_Long     italic_angle;
     77     FT_Bool     is_fixed_pitch;
     78     FT_Short    underline_position;
     79     FT_UShort   underline_thickness;
     80 
     81   } PS_FontInfoRec;
     82 
     83 
     84   /*************************************************************************/
     85   /*                                                                       */
     86   /* <Struct>                                                              */
     87   /*    PS_FontInfo                                                        */
     88   /*                                                                       */
     89   /* <Description>                                                         */
     90   /*    A handle to a @PS_FontInfoRec structure.                           */
     91   /*                                                                       */
     92   typedef struct PS_FontInfoRec_*  PS_FontInfo;
     93 
     94 
     95   /*************************************************************************/
     96   /*                                                                       */
     97   /* <Struct>                                                              */
     98   /*    T1_FontInfo                                                        */
     99   /*                                                                       */
    100   /* <Description>                                                         */
    101   /*    This type is equivalent to @PS_FontInfoRec.  It is deprecated but  */
    102   /*    kept to maintain source compatibility between various versions of  */
    103   /*    FreeType.                                                          */
    104   /*                                                                       */
    105   typedef PS_FontInfoRec  T1_FontInfo;
    106 
    107 
    108   /*************************************************************************/
    109   /*                                                                       */
    110   /* <Struct>                                                              */
    111   /*    PS_PrivateRec                                                      */
    112   /*                                                                       */
    113   /* <Description>                                                         */
    114   /*    A structure used to model a Type~1 or Type~2 private dictionary.   */
    115   /*    Note that for Multiple Master fonts, each instance has its own     */
    116   /*    Private dictionary.                                                */
    117   /*                                                                       */
    118   typedef struct  PS_PrivateRec_
    119   {
    120     FT_Int     unique_id;
    121     FT_Int     lenIV;
    122 
    123     FT_Byte    num_blue_values;
    124     FT_Byte    num_other_blues;
    125     FT_Byte    num_family_blues;
    126     FT_Byte    num_family_other_blues;
    127 
    128     FT_Short   blue_values[14];
    129     FT_Short   other_blues[10];
    130 
    131     FT_Short   family_blues      [14];
    132     FT_Short   family_other_blues[10];
    133 
    134     FT_Fixed   blue_scale;
    135     FT_Int     blue_shift;
    136     FT_Int     blue_fuzz;
    137 
    138     FT_UShort  standard_width[1];
    139     FT_UShort  standard_height[1];
    140 
    141     FT_Byte    num_snap_widths;
    142     FT_Byte    num_snap_heights;
    143     FT_Bool    force_bold;
    144     FT_Bool    round_stem_up;
    145 
    146     FT_Short   snap_widths [13];  /* including std width  */
    147     FT_Short   snap_heights[13];  /* including std height */
    148 
    149     FT_Fixed   expansion_factor;
    150 
    151     FT_Long    language_group;
    152     FT_Long    password;
    153 
    154     FT_Short   min_feature[2];
    155 
    156   } PS_PrivateRec;
    157 
    158 
    159   /*************************************************************************/
    160   /*                                                                       */
    161   /* <Struct>                                                              */
    162   /*    PS_Private                                                         */
    163   /*                                                                       */
    164   /* <Description>                                                         */
    165   /*    A handle to a @PS_PrivateRec structure.                            */
    166   /*                                                                       */
    167   typedef struct PS_PrivateRec_*  PS_Private;
    168 
    169 
    170   /*************************************************************************/
    171   /*                                                                       */
    172   /* <Struct>                                                              */
    173   /*    T1_Private                                                         */
    174   /*                                                                       */
    175   /* <Description>                                                         */
    176   /*   This type is equivalent to @PS_PrivateRec.  It is deprecated but    */
    177   /*   kept to maintain source compatibility between various versions of   */
    178   /*   FreeType.                                                           */
    179   /*                                                                       */
    180   typedef PS_PrivateRec  T1_Private;
    181 
    182 
    183   /*************************************************************************/
    184   /*                                                                       */
    185   /* <Enum>                                                                */
    186   /*    T1_Blend_Flags                                                     */
    187   /*                                                                       */
    188   /* <Description>                                                         */
    189   /*    A set of flags used to indicate which fields are present in a      */
    190   /*    given blend dictionary (font info or private).  Used to support    */
    191   /*    Multiple Masters fonts.                                            */
    192   /*                                                                       */
    193   typedef enum  T1_Blend_Flags_
    194   {
    195     /*# required fields in a FontInfo blend dictionary */
    196     T1_BLEND_UNDERLINE_POSITION = 0,
    197     T1_BLEND_UNDERLINE_THICKNESS,
    198     T1_BLEND_ITALIC_ANGLE,
    199 
    200     /*# required fields in a Private blend dictionary */
    201     T1_BLEND_BLUE_VALUES,
    202     T1_BLEND_OTHER_BLUES,
    203     T1_BLEND_STANDARD_WIDTH,
    204     T1_BLEND_STANDARD_HEIGHT,
    205     T1_BLEND_STEM_SNAP_WIDTHS,
    206     T1_BLEND_STEM_SNAP_HEIGHTS,
    207     T1_BLEND_BLUE_SCALE,
    208     T1_BLEND_BLUE_SHIFT,
    209     T1_BLEND_FAMILY_BLUES,
    210     T1_BLEND_FAMILY_OTHER_BLUES,
    211     T1_BLEND_FORCE_BOLD,
    212 
    213     /*# never remove */
    214     T1_BLEND_MAX
    215 
    216   } T1_Blend_Flags;
    217 
    218   /* */
    219 
    220 
    221   /*# backwards compatible definitions */
    222 #define t1_blend_underline_position   T1_BLEND_UNDERLINE_POSITION
    223 #define t1_blend_underline_thickness  T1_BLEND_UNDERLINE_THICKNESS
    224 #define t1_blend_italic_angle         T1_BLEND_ITALIC_ANGLE
    225 #define t1_blend_blue_values          T1_BLEND_BLUE_VALUES
    226 #define t1_blend_other_blues          T1_BLEND_OTHER_BLUES
    227 #define t1_blend_standard_widths      T1_BLEND_STANDARD_WIDTH
    228 #define t1_blend_standard_height      T1_BLEND_STANDARD_HEIGHT
    229 #define t1_blend_stem_snap_widths     T1_BLEND_STEM_SNAP_WIDTHS
    230 #define t1_blend_stem_snap_heights    T1_BLEND_STEM_SNAP_HEIGHTS
    231 #define t1_blend_blue_scale           T1_BLEND_BLUE_SCALE
    232 #define t1_blend_blue_shift           T1_BLEND_BLUE_SHIFT
    233 #define t1_blend_family_blues         T1_BLEND_FAMILY_BLUES
    234 #define t1_blend_family_other_blues   T1_BLEND_FAMILY_OTHER_BLUES
    235 #define t1_blend_force_bold           T1_BLEND_FORCE_BOLD
    236 #define t1_blend_max                  T1_BLEND_MAX
    237 
    238 
    239   /* maximum number of Multiple Masters designs, as defined in the spec */
    240 #define T1_MAX_MM_DESIGNS     16
    241 
    242   /* maximum number of Multiple Masters axes, as defined in the spec */
    243 #define T1_MAX_MM_AXIS        4
    244 
    245   /* maximum number of elements in a design map */
    246 #define T1_MAX_MM_MAP_POINTS  20
    247 
    248 
    249   /* this structure is used to store the BlendDesignMap entry for an axis */
    250   typedef struct  PS_DesignMap_
    251   {
    252     FT_Byte    num_points;
    253     FT_Long*   design_points;
    254     FT_Fixed*  blend_points;
    255 
    256   } PS_DesignMapRec, *PS_DesignMap;
    257 
    258   /* backwards-compatible definition */
    259   typedef PS_DesignMapRec  T1_DesignMap;
    260 
    261 
    262   typedef struct  PS_BlendRec_
    263   {
    264     FT_UInt          num_designs;
    265     FT_UInt          num_axis;
    266 
    267     FT_String*       axis_names[T1_MAX_MM_AXIS];
    268     FT_Fixed*        design_pos[T1_MAX_MM_DESIGNS];
    269     PS_DesignMapRec  design_map[T1_MAX_MM_AXIS];
    270 
    271     FT_Fixed*        weight_vector;
    272     FT_Fixed*        default_weight_vector;
    273 
    274     PS_FontInfo      font_infos[T1_MAX_MM_DESIGNS + 1];
    275     PS_Private       privates  [T1_MAX_MM_DESIGNS + 1];
    276 
    277     FT_ULong         blend_bitflags;
    278 
    279     FT_BBox*         bboxes    [T1_MAX_MM_DESIGNS + 1];
    280 
    281     /* since 2.3.0 */
    282 
    283     /* undocumented, optional: the default design instance;   */
    284     /* corresponds to default_weight_vector --                */
    285     /* num_default_design_vector == 0 means it is not present */
    286     /* in the font and associated metrics files               */
    287     FT_UInt          default_design_vector[T1_MAX_MM_DESIGNS];
    288     FT_UInt          num_default_design_vector;
    289 
    290   } PS_BlendRec, *PS_Blend;
    291 
    292 
    293   /* backwards-compatible definition */
    294   typedef PS_BlendRec  T1_Blend;
    295 
    296 
    297   /*************************************************************************/
    298   /*                                                                       */
    299   /* <Struct>                                                              */
    300   /*    CID_FaceDictRec                                                    */
    301   /*                                                                       */
    302   /* <Description>                                                         */
    303   /*    A structure used to represent data in a CID top-level dictionary.  */
    304   /*                                                                       */
    305   typedef struct  CID_FaceDictRec_
    306   {
    307     PS_PrivateRec  private_dict;
    308 
    309     FT_UInt        len_buildchar;
    310     FT_Fixed       forcebold_threshold;
    311     FT_Pos         stroke_width;
    312     FT_Fixed       expansion_factor;
    313 
    314     FT_Byte        paint_type;
    315     FT_Byte        font_type;
    316     FT_Matrix      font_matrix;
    317     FT_Vector      font_offset;
    318 
    319     FT_UInt        num_subrs;
    320     FT_ULong       subrmap_offset;
    321     FT_Int         sd_bytes;
    322 
    323   } CID_FaceDictRec;
    324 
    325 
    326   /*************************************************************************/
    327   /*                                                                       */
    328   /* <Struct>                                                              */
    329   /*    CID_FaceDict                                                       */
    330   /*                                                                       */
    331   /* <Description>                                                         */
    332   /*    A handle to a @CID_FaceDictRec structure.                          */
    333   /*                                                                       */
    334   typedef struct CID_FaceDictRec_*  CID_FaceDict;
    335 
    336   /* */
    337 
    338 
    339   /* backwards-compatible definition */
    340   typedef CID_FaceDictRec  CID_FontDict;
    341 
    342 
    343   /*************************************************************************/
    344   /*                                                                       */
    345   /* <Struct>                                                              */
    346   /*    CID_FaceInfoRec                                                    */
    347   /*                                                                       */
    348   /* <Description>                                                         */
    349   /*    A structure used to represent CID Face information.                */
    350   /*                                                                       */
    351   typedef struct  CID_FaceInfoRec_
    352   {
    353     FT_String*      cid_font_name;
    354     FT_Fixed        cid_version;
    355     FT_Int          cid_font_type;
    356 
    357     FT_String*      registry;
    358     FT_String*      ordering;
    359     FT_Int          supplement;
    360 
    361     PS_FontInfoRec  font_info;
    362     FT_BBox         font_bbox;
    363     FT_ULong        uid_base;
    364 
    365     FT_Int          num_xuid;
    366     FT_ULong        xuid[16];
    367 
    368     FT_ULong        cidmap_offset;
    369     FT_Int          fd_bytes;
    370     FT_Int          gd_bytes;
    371     FT_ULong        cid_count;
    372 
    373     FT_Int          num_dicts;
    374     CID_FaceDict    font_dicts;
    375 
    376     FT_ULong        data_offset;
    377 
    378   } CID_FaceInfoRec;
    379 
    380 
    381   /*************************************************************************/
    382   /*                                                                       */
    383   /* <Struct>                                                              */
    384   /*    CID_FaceInfo                                                       */
    385   /*                                                                       */
    386   /* <Description>                                                         */
    387   /*    A handle to a @CID_FaceInfoRec structure.                          */
    388   /*                                                                       */
    389   typedef struct CID_FaceInfoRec_*  CID_FaceInfo;
    390 
    391 
    392   /*************************************************************************/
    393   /*                                                                       */
    394   /* <Struct>                                                              */
    395   /*    CID_Info                                                           */
    396   /*                                                                       */
    397   /* <Description>                                                         */
    398   /*   This type is equivalent to @CID_FaceInfoRec.  It is deprecated but  */
    399   /*   kept to maintain source compatibility between various versions of   */
    400   /*   FreeType.                                                           */
    401   /*                                                                       */
    402   typedef CID_FaceInfoRec  CID_Info;
    403 
    404 
    405   /************************************************************************
    406    *
    407    * @function:
    408    *    FT_Has_PS_Glyph_Names
    409    *
    410    * @description:
    411    *    Return true if a given face provides reliable PostScript glyph
    412    *    names.  This is similar to using the @FT_HAS_GLYPH_NAMES macro,
    413    *    except that certain fonts (mostly TrueType) contain incorrect
    414    *    glyph name tables.
    415    *
    416    *    When this function returns true, the caller is sure that the glyph
    417    *    names returned by @FT_Get_Glyph_Name are reliable.
    418    *
    419    * @input:
    420    *    face ::
    421    *       face handle
    422    *
    423    * @return:
    424    *    Boolean.  True if glyph names are reliable.
    425    *
    426    */
    427   FT_EXPORT( FT_Int )
    428   FT_Has_PS_Glyph_Names( FT_Face  face );
    429 
    430 
    431   /************************************************************************
    432    *
    433    * @function:
    434    *    FT_Get_PS_Font_Info
    435    *
    436    * @description:
    437    *    Retrieve the @PS_FontInfoRec structure corresponding to a given
    438    *    PostScript font.
    439    *
    440    * @input:
    441    *    face ::
    442    *       PostScript face handle.
    443    *
    444    * @output:
    445    *    afont_info ::
    446    *       Output font info structure pointer.
    447    *
    448    * @return:
    449    *    FreeType error code.  0~means success.
    450    *
    451    * @note:
    452    *    The string pointers within the font info structure are owned by
    453    *    the face and don't need to be freed by the caller.
    454    *
    455    *    If the font's format is not PostScript-based, this function will
    456    *    return the `FT_Err_Invalid_Argument' error code.
    457    *
    458    */
    459   FT_EXPORT( FT_Error )
    460   FT_Get_PS_Font_Info( FT_Face      face,
    461                        PS_FontInfo  afont_info );
    462 
    463 
    464   /************************************************************************
    465    *
    466    * @function:
    467    *    FT_Get_PS_Font_Private
    468    *
    469    * @description:
    470    *    Retrieve the @PS_PrivateRec structure corresponding to a given
    471    *    PostScript font.
    472    *
    473    * @input:
    474    *    face ::
    475    *       PostScript face handle.
    476    *
    477    * @output:
    478    *    afont_private ::
    479    *       Output private dictionary structure pointer.
    480    *
    481    * @return:
    482    *    FreeType error code.  0~means success.
    483    *
    484    * @note:
    485    *    The string pointers within the @PS_PrivateRec structure are owned by
    486    *    the face and don't need to be freed by the caller.
    487    *
    488    *    If the font's format is not PostScript-based, this function returns
    489    *    the `FT_Err_Invalid_Argument' error code.
    490    *
    491    */
    492   FT_EXPORT( FT_Error )
    493   FT_Get_PS_Font_Private( FT_Face     face,
    494                           PS_Private  afont_private );
    495 
    496 
    497   /*************************************************************************/
    498   /*                                                                       */
    499   /* <Enum>                                                                */
    500   /*    T1_EncodingType                                                    */
    501   /*                                                                       */
    502   /* <Description>                                                         */
    503   /*    An enumeration describing the `Encoding' entry in a Type 1         */
    504   /*    dictionary.                                                        */
    505   /*                                                                       */
    506   typedef enum  T1_EncodingType_
    507   {
    508     T1_ENCODING_TYPE_NONE = 0,
    509     T1_ENCODING_TYPE_ARRAY,
    510     T1_ENCODING_TYPE_STANDARD,
    511     T1_ENCODING_TYPE_ISOLATIN1,
    512     T1_ENCODING_TYPE_EXPERT
    513 
    514   } T1_EncodingType;
    515 
    516 
    517   /*************************************************************************/
    518   /*                                                                       */
    519   /* <Enum>                                                                */
    520   /*    PS_Dict_Keys                                                       */
    521   /*                                                                       */
    522   /* <Description>                                                         */
    523   /*    An enumeration used in calls to @FT_Get_PS_Font_Value to identify  */
    524   /*    the Type~1 dictionary entry to retrieve.                           */
    525   /*                                                                       */
    526   typedef enum  PS_Dict_Keys_
    527   {
    528     /* conventionally in the font dictionary */
    529     PS_DICT_FONT_TYPE,              /* FT_Byte         */
    530     PS_DICT_FONT_MATRIX,            /* FT_Fixed        */
    531     PS_DICT_FONT_BBOX,              /* FT_Fixed        */
    532     PS_DICT_PAINT_TYPE,             /* FT_Byte         */
    533     PS_DICT_FONT_NAME,              /* FT_String*      */
    534     PS_DICT_UNIQUE_ID,              /* FT_Int          */
    535     PS_DICT_NUM_CHAR_STRINGS,       /* FT_Int          */
    536     PS_DICT_CHAR_STRING_KEY,        /* FT_String*      */
    537     PS_DICT_CHAR_STRING,            /* FT_String*      */
    538     PS_DICT_ENCODING_TYPE,          /* T1_EncodingType */
    539     PS_DICT_ENCODING_ENTRY,         /* FT_String*      */
    540 
    541     /* conventionally in the font Private dictionary */
    542     PS_DICT_NUM_SUBRS,              /* FT_Int     */
    543     PS_DICT_SUBR,                   /* FT_String* */
    544     PS_DICT_STD_HW,                 /* FT_UShort  */
    545     PS_DICT_STD_VW,                 /* FT_UShort  */
    546     PS_DICT_NUM_BLUE_VALUES,        /* FT_Byte    */
    547     PS_DICT_BLUE_VALUE,             /* FT_Short   */
    548     PS_DICT_BLUE_FUZZ,              /* FT_Int     */
    549     PS_DICT_NUM_OTHER_BLUES,        /* FT_Byte    */
    550     PS_DICT_OTHER_BLUE,             /* FT_Short   */
    551     PS_DICT_NUM_FAMILY_BLUES,       /* FT_Byte    */
    552     PS_DICT_FAMILY_BLUE,            /* FT_Short   */
    553     PS_DICT_NUM_FAMILY_OTHER_BLUES, /* FT_Byte    */
    554     PS_DICT_FAMILY_OTHER_BLUE,      /* FT_Short   */
    555     PS_DICT_BLUE_SCALE,             /* FT_Fixed   */
    556     PS_DICT_BLUE_SHIFT,             /* FT_Int     */
    557     PS_DICT_NUM_STEM_SNAP_H,        /* FT_Byte    */
    558     PS_DICT_STEM_SNAP_H,            /* FT_Short   */
    559     PS_DICT_NUM_STEM_SNAP_V,        /* FT_Byte    */
    560     PS_DICT_STEM_SNAP_V,            /* FT_Short   */
    561     PS_DICT_FORCE_BOLD,             /* FT_Bool    */
    562     PS_DICT_RND_STEM_UP,            /* FT_Bool    */
    563     PS_DICT_MIN_FEATURE,            /* FT_Short   */
    564     PS_DICT_LEN_IV,                 /* FT_Int     */
    565     PS_DICT_PASSWORD,               /* FT_Long    */
    566     PS_DICT_LANGUAGE_GROUP,         /* FT_Long    */
    567 
    568     /* conventionally in the font FontInfo dictionary */
    569     PS_DICT_VERSION,                /* FT_String* */
    570     PS_DICT_NOTICE,                 /* FT_String* */
    571     PS_DICT_FULL_NAME,              /* FT_String* */
    572     PS_DICT_FAMILY_NAME,            /* FT_String* */
    573     PS_DICT_WEIGHT,                 /* FT_String* */
    574     PS_DICT_IS_FIXED_PITCH,         /* FT_Bool    */
    575     PS_DICT_UNDERLINE_POSITION,     /* FT_Short   */
    576     PS_DICT_UNDERLINE_THICKNESS,    /* FT_UShort  */
    577     PS_DICT_FS_TYPE,                /* FT_UShort  */
    578     PS_DICT_ITALIC_ANGLE,           /* FT_Long    */
    579 
    580     PS_DICT_MAX = PS_DICT_ITALIC_ANGLE
    581 
    582   } PS_Dict_Keys;
    583 
    584 
    585   /************************************************************************
    586    *
    587    * @function:
    588    *    FT_Get_PS_Font_Value
    589    *
    590    * @description:
    591    *    Retrieve the value for the supplied key from a PostScript font.
    592    *
    593    * @input:
    594    *    face ::
    595    *       PostScript face handle.
    596    *
    597    *    key ::
    598    *       An enumeration value representing the dictionary key to retrieve.
    599    *
    600    *    idx ::
    601    *       For array values, this specifies the index to be returned.
    602    *
    603    *    value ::
    604    *       A pointer to memory into which to write the value.
    605    *
    606    *    valen_len ::
    607    *       The size, in bytes, of the memory supplied for the value.
    608    *
    609    * @output:
    610    *    value ::
    611    *       The value matching the above key, if it exists.
    612    *
    613    * @return:
    614    *    The amount of memory (in bytes) required to hold the requested
    615    *    value (if it exists, -1 otherwise).
    616    *
    617    * @note:
    618    *    The values returned are not pointers into the internal structures of
    619    *    the face, but are `fresh' copies, so that the memory containing them
    620    *    belongs to the calling application.  This also enforces the
    621    *    `read-only' nature of these values, i.e., this function cannot be
    622    *    used to manipulate the face.
    623    *
    624    *    `value' is a void pointer because the values returned can be of
    625    *    various types.
    626    *
    627    *    If either `value' is NULL or `value_len' is too small, just the
    628    *    required memory size for the requested entry is returned.
    629    *
    630    *    The `idx' parameter is used, not only to retrieve elements of, for
    631    *    example, the FontMatrix or FontBBox, but also to retrieve name keys
    632    *    from the CharStrings dictionary, and the charstrings themselves.  It
    633    *    is ignored for atomic values.
    634    *
    635    *    PS_DICT_BLUE_SCALE returns a value that is scaled up by 1000.  To
    636    *    get the value as in the font stream, you need to divide by
    637    *    65536000.0 (to remove the FT_Fixed scale, and the x1000 scale).
    638    *
    639    *    IMPORTANT: Only key/value pairs read by the FreeType interpreter can
    640    *    be retrieved.  So, for example, PostScript procedures such as NP,
    641    *    ND, and RD are not available.  Arbitrary keys are, obviously, not be
    642    *    available either.
    643    *
    644    *    If the font's format is not PostScript-based, this function returns
    645    *    the `FT_Err_Invalid_Argument' error code.
    646    *
    647    */
    648   FT_EXPORT( FT_Long )
    649   FT_Get_PS_Font_Value( FT_Face       face,
    650                         PS_Dict_Keys  key,
    651                         FT_UInt       idx,
    652                         void         *value,
    653                         FT_Long       value_len );
    654 
    655   /* */
    656 
    657 FT_END_HEADER
    658 
    659 #endif /* __T1TABLES_H__ */
    660 
    661 
    662 /* END */
    663