freetype2/freetype/ftpfr.h

0001 /****************************************************************************
0002  *
0003  * ftpfr.h
0004  *
0005  *   FreeType API for accessing PFR-specific data (specification only).
0006  *
0007  * Copyright (C) 2002-2023 by
0008  * David Turner, Robert Wilhelm, and Werner Lemberg.
0009  *
0010  * This file is part of the FreeType project, and may only be used,
0011  * modified, and distributed under the terms of the FreeType project
0012  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0013  * this file you indicate that you have read the license and
0014  * understand and accept it fully.
0015  *
0016  */
0017
0018
0019 #ifndef FTPFR_H_
0020 #define FTPFR_H_
0021
0022 #include <freetype/freetype.h>
0023
0024 #ifdef FREETYPE_H
0025 #error "freetype.h of FreeType 1 has been loaded!"
0026 #error "Please fix the directory search order for header files"
0027 #error "so that freetype.h of FreeType 2 is found first."
0028 #endif
0029
0030
0031 FT_BEGIN_HEADER
0032
0033
0034   /**************************************************************************
0035    *
0036    * @section:
0037    *   pfr_fonts
0038    *
0039    * @title:
0040    *   PFR Fonts
0041    *
0042    * @abstract:
0043    *   PFR/TrueDoc-specific API.
0044    *
0045    * @description:
0046    *   This section contains the declaration of PFR-specific functions.
0047    *
0048    */
0049
0050
0051   /**************************************************************************
0052    *
0053    * @function:
0054    *    FT_Get_PFR_Metrics
0055    *
0056    * @description:
0057    *    Return the outline and metrics resolutions of a given PFR face.
0058    *
0059    * @input:
0060    *    face ::
0061    *      Handle to the input face.  It can be a non-PFR face.
0062    *
0063    * @output:
0064    *    aoutline_resolution ::
0065    *      Outline resolution.  This is equivalent to `face->units_per_EM` for
0066    *      non-PFR fonts.  Optional (parameter can be `NULL`).
0067    *
0068    *    ametrics_resolution ::
0069    *      Metrics resolution.  This is equivalent to `outline_resolution` for
0070    *      non-PFR fonts.  Optional (parameter can be `NULL`).
0071    *
0072    *    ametrics_x_scale ::
0073    *      A 16.16 fixed-point number used to scale distance expressed in
0074    *      metrics units to device subpixels.  This is equivalent to
0075    *      `face->size->x_scale`, but for metrics only.  Optional (parameter
0076    *      can be `NULL`).
0077    *
0078    *    ametrics_y_scale ::
0079    *      Same as `ametrics_x_scale` but for the vertical direction.
0080    *      optional (parameter can be `NULL`).
0081    *
0082    * @return:
0083    *    FreeType error code.  0~means success.
0084    *
0085    * @note:
0086    *   If the input face is not a PFR, this function will return an error.
0087    *   However, in all cases, it will return valid values.
0088    */
0089   FT_EXPORT( FT_Error )
0090   FT_Get_PFR_Metrics( FT_Face    face,
0091                       FT_UInt   *aoutline_resolution,
0092                       FT_UInt   *ametrics_resolution,
0093                       FT_Fixed  *ametrics_x_scale,
0094                       FT_Fixed  *ametrics_y_scale );
0095
0096
0097   /**************************************************************************
0098    *
0099    * @function:
0100    *    FT_Get_PFR_Kerning
0101    *
0102    * @description:
0103    *    Return the kerning pair corresponding to two glyphs in a PFR face.
0104    *    The distance is expressed in metrics units, unlike the result of
0105    *    @FT_Get_Kerning.
0106    *
0107    * @input:
0108    *    face ::
0109    *      A handle to the input face.
0110    *
0111    *    left ::
0112    *      Index of the left glyph.
0113    *
0114    *    right ::
0115    *      Index of the right glyph.
0116    *
0117    * @output:
0118    *    avector ::
0119    *      A kerning vector.
0120    *
0121    * @return:
0122    *    FreeType error code.  0~means success.
0123    *
0124    * @note:
0125    *    This function always return distances in original PFR metrics units.
0126    *    This is unlike @FT_Get_Kerning with the @FT_KERNING_UNSCALED mode,
0127    *    which always returns distances converted to outline units.
0128    *
0129    *    You can use the value of the `x_scale` and `y_scale` parameters
0130    *    returned by @FT_Get_PFR_Metrics to scale these to device subpixels.
0131    */
0132   FT_EXPORT( FT_Error )
0133   FT_Get_PFR_Kerning( FT_Face     face,
0134                       FT_UInt     left,
0135                       FT_UInt     right,
0136                       FT_Vector  *avector );
0137
0138
0139   /**************************************************************************
0140    *
0141    * @function:
0142    *    FT_Get_PFR_Advance
0143    *
0144    * @description:
0145    *    Return a given glyph advance, expressed in original metrics units,
0146    *    from a PFR font.
0147    *
0148    * @input:
0149    *    face ::
0150    *      A handle to the input face.
0151    *
0152    *    gindex ::
0153    *      The glyph index.
0154    *
0155    * @output:
0156    *    aadvance ::
0157    *      The glyph advance in metrics units.
0158    *
0159    * @return:
0160    *    FreeType error code.  0~means success.
0161    *
0162    * @note:
0163    *    You can use the `x_scale` or `y_scale` results of @FT_Get_PFR_Metrics
0164    *    to convert the advance to device subpixels (i.e., 1/64 of pixels).
0165    */
0166   FT_EXPORT( FT_Error )
0167   FT_Get_PFR_Advance( FT_Face   face,
0168                       FT_UInt   gindex,
0169                       FT_Pos   *aadvance );
0170
0171   /* */
0172
0173
0174 FT_END_HEADER
0175
0176 #endif /* FTPFR_H_ */
0177
0178
0179 /* END */