include/freetype/ftpfr.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftpfr.h                                                                */
   4 /*                                                                         */
   5 /*    FreeType API for accessing PFR-specific data (specification only).   */
   6 /*                                                                         */
   7 /*  Copyright 2002, 2003, 2004, 2006, 2008, 2009 by                        */
   8 /*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
   9 /*                                                                         */
  10 /*  This file is part of the FreeType project, and may only be used,       */
  11 /*  modified, and distributed under the terms of the FreeType project      */
  12 /*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
  13 /*  this file you indicate that you have read the license and              */
  14 /*  understand and accept it fully.                                        */
  15 /*                                                                         */
  16 /***************************************************************************/
  17
  18
  19 #ifndef __FTPFR_H__
  20 #define __FTPFR_H__
  21
  22 #include <ft2build.h>
  23 #include FT_FREETYPE_H
  24
  25 #ifdef FREETYPE_H
  26 #error "freetype.h of FreeType 1 has been loaded!"
  27 #error "Please fix the directory search order for header files"
  28 #error "so that freetype.h of FreeType 2 is found first."
  29 #endif
  30
  31
  32 FT_BEGIN_HEADER
  33
  34
  35   /*************************************************************************/
  36   /*                                                                       */
  37   /* <Section>                                                             */
  38   /*    pfr_fonts                                                          */
  39   /*                                                                       */
  40   /* <Title>                                                               */
  41   /*    PFR Fonts                                                          */
  42   /*                                                                       */
  43   /* <Abstract>                                                            */
  44   /*    PFR/TrueDoc specific API.                                          */
  45   /*                                                                       */
  46   /* <Description>                                                         */
  47   /*    This section contains the declaration of PFR-specific functions.   */
  48   /*                                                                       */
  49   /*************************************************************************/
  50
  51
  52  /**********************************************************************
  53   *
  54   * @function:
  55   *    FT_Get_PFR_Metrics
  56   *
  57   * @description:
  58   *    Return the outline and metrics resolutions of a given PFR face.
  59   *
  60   * @input:
  61   *    face :: Handle to the input face.  It can be a non-PFR face.
  62   *
  63   * @output:
  64   *    aoutline_resolution ::
  65   *      Outline resolution.  This is equivalent to `face->units_per_EM'
  66   *      for non-PFR fonts.  Optional (parameter can be NULL).
  67   *
  68   *    ametrics_resolution ::
  69   *      Metrics resolution.  This is equivalent to `outline_resolution'
  70   *      for non-PFR fonts.  Optional (parameter can be NULL).
  71   *
  72   *    ametrics_x_scale ::
  73   *      A 16.16 fixed-point number used to scale distance expressed
  74   *      in metrics units to device sub-pixels.  This is equivalent to
  75   *      `face->size->x_scale', but for metrics only.  Optional (parameter
  76   *      can be NULL).
  77   *
  78   *    ametrics_y_scale ::
  79   *      Same as `ametrics_x_scale' but for the vertical direction.
  80   *      optional (parameter can be NULL).
  81   *
  82   * @return:
  83   *    FreeType error code.  0~means success.
  84   *
  85   * @note:
  86   *   If the input face is not a PFR, this function will return an error.
  87   *   However, in all cases, it will return valid values.
  88   */
  89   FT_EXPORT( FT_Error )
  90   FT_Get_PFR_Metrics( FT_Face    face,
  91                       FT_UInt   *aoutline_resolution,
  92                       FT_UInt   *ametrics_resolution,
  93                       FT_Fixed  *ametrics_x_scale,
  94                       FT_Fixed  *ametrics_y_scale );
  95
  96
  97  /**********************************************************************
  98   *
  99   * @function:
 100   *    FT_Get_PFR_Kerning
 101   *
 102   * @description:
 103   *    Return the kerning pair corresponding to two glyphs in a PFR face.
 104   *    The distance is expressed in metrics units, unlike the result of
 105   *    @FT_Get_Kerning.
 106   *
 107   * @input:
 108   *    face  :: A handle to the input face.
 109   *
 110   *    left  :: Index of the left glyph.
 111   *
 112   *    right :: Index of the right glyph.
 113   *
 114   * @output:
 115   *    avector :: A kerning vector.
 116   *
 117   * @return:
 118   *    FreeType error code.  0~means success.
 119   *
 120   * @note:
 121   *    This function always return distances in original PFR metrics
 122   *    units.  This is unlike @FT_Get_Kerning with the @FT_KERNING_UNSCALED
 123   *    mode, which always returns distances converted to outline units.
 124   *
 125   *    You can use the value of the `x_scale' and `y_scale' parameters
 126   *    returned by @FT_Get_PFR_Metrics to scale these to device sub-pixels.
 127   */
 128   FT_EXPORT( FT_Error )
 129   FT_Get_PFR_Kerning( FT_Face     face,
 130                       FT_UInt     left,
 131                       FT_UInt     right,
 132                       FT_Vector  *avector );
 133
 134
 135  /**********************************************************************
 136   *
 137   * @function:
 138   *    FT_Get_PFR_Advance
 139   *
 140   * @description:
 141   *    Return a given glyph advance, expressed in original metrics units,
 142   *    from a PFR font.
 143   *
 144   * @input:
 145   *    face   :: A handle to the input face.
 146   *
 147   *    gindex :: The glyph index.
 148   *
 149   * @output:
 150   *    aadvance :: The glyph advance in metrics units.
 151   *
 152   * @return:
 153   *    FreeType error code.  0~means success.
 154   *
 155   * @note:
 156   *    You can use the `x_scale' or `y_scale' results of @FT_Get_PFR_Metrics
 157   *    to convert the advance to device sub-pixels (i.e., 1/64th of pixels).
 158   */
 159   FT_EXPORT( FT_Error )
 160   FT_Get_PFR_Advance( FT_Face   face,
 161                       FT_UInt   gindex,
 162                       FT_Pos   *aadvance );
 163
 164  /* */
 165
 166
 167 FT_END_HEADER
 168
 169 #endif /* __FTPFR_H__ */
 170
 171
 172 /* END */