1 /****************************************************************************
2  *
3  * ftpfr.h
4  *
5  *   FreeType API for accessing PFR-specific data (specification only).
6  *
7  * Copyright 2002-2018 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 ::
62    *      Handle to the input face.  It can be a non-PFR face.
63    *
64    * @output:
65    *    aoutline_resolution ::
66    *      Outline resolution.  This is equivalent to `face->units_per_EM'
67    *      for non-PFR fonts.  Optional (parameter can be NULL).
68    *
69    *    ametrics_resolution ::
70    *      Metrics resolution.  This is equivalent to `outline_resolution'
71    *      for non-PFR fonts.  Optional (parameter can be NULL).
72    *
73    *    ametrics_x_scale ::
74    *      A 16.16 fixed-point number used to scale distance expressed
75    *      in metrics units to device subpixels.  This is equivalent to
76    *      `face->size->x_scale', but for metrics only.  Optional (parameter
77    *      can be NULL).
78    *
79    *    ametrics_y_scale ::
80    *      Same as `ametrics_x_scale' but for the vertical direction.
81    *      optional (parameter can be NULL).
82    *
83    * @return:
84    *    FreeType error code.  0~means success.
85    *
86    * @note:
87    *   If the input face is not a PFR, this function will return an error.
88    *   However, in all cases, it will return valid values.
89    */
90   FT_EXPORT( FT_Error )
91   FT_Get_PFR_Metrics( FT_Face    face,
92                       FT_UInt   *aoutline_resolution,
93                       FT_UInt   *ametrics_resolution,
94                       FT_Fixed  *ametrics_x_scale,
95                       FT_Fixed  *ametrics_y_scale );
96 
97 
98   /**********************************************************************
99    *
100    * @function:
101    *    FT_Get_PFR_Kerning
102    *
103    * @description:
104    *    Return the kerning pair corresponding to two glyphs in a PFR face.
105    *    The distance is expressed in metrics units, unlike the result of
106    *    @FT_Get_Kerning.
107    *
108    * @input:
109    *    face ::
110    *      A handle to the input face.
111    *
112    *    left ::
113    *      Index of the left glyph.
114    *
115    *    right ::
116    *      Index of the right glyph.
117    *
118    * @output:
119    *    avector ::
120    *      A kerning vector.
121    *
122    * @return:
123    *    FreeType error code.  0~means success.
124    *
125    * @note:
126    *    This function always return distances in original PFR metrics
127    *    units.  This is unlike @FT_Get_Kerning with the @FT_KERNING_UNSCALED
128    *    mode, which always returns distances converted to outline units.
129    *
130    *    You can use the value of the `x_scale' and `y_scale' parameters
131    *    returned by @FT_Get_PFR_Metrics to scale these to device subpixels.
132    */
133   FT_EXPORT( FT_Error )
134   FT_Get_PFR_Kerning( FT_Face     face,
135                       FT_UInt     left,
136                       FT_UInt     right,
137                       FT_Vector  *avector );
138 
139 
140   /**********************************************************************
141    *
142    * @function:
143    *    FT_Get_PFR_Advance
144    *
145    * @description:
146    *    Return a given glyph advance, expressed in original metrics units,
147    *    from a PFR font.
148    *
149    * @input:
150    *    face ::
151    *      A handle to the input face.
152    *
153    *    gindex ::
154    *      The glyph index.
155    *
156    * @output:
157    *    aadvance ::
158    *      The glyph advance in metrics units.
159    *
160    * @return:
161    *    FreeType error code.  0~means success.
162    *
163    * @note:
164    *    You can use the `x_scale' or `y_scale' results of @FT_Get_PFR_Metrics
165    *    to convert the advance to device subpixels (i.e., 1/64th of pixels).
166    */
167   FT_EXPORT( FT_Error )
168   FT_Get_PFR_Advance( FT_Face   face,
169                       FT_UInt   gindex,
170                       FT_Pos   *aadvance );
171 
172   /* */
173 
174 
175 FT_END_HEADER
176 
177 #endif /* FTPFR_H_ */
178 
179 
180 /* END */
181