1 /****************************************************************************
2 *
3 * ftpfr.h
4 *
5 * FreeType API for accessing PFR-specific data (specification only).
6 *
7 * Copyright (C) 2002-2023 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 <freetype/freetype.h>
23
24 #ifdef FREETYPE_H
25 #error "freetype.h of FreeType 1 has been loaded!"
26 #error "Please fix the directory search order for header files"
27 #error "so that freetype.h of FreeType 2 is found first."
28 #endif
29
30
31 FT_BEGIN_HEADER
32
33
34 /**************************************************************************
35 *
36 * @section:
37 * pfr_fonts
38 *
39 * @title:
40 * PFR Fonts
41 *
42 * @abstract:
43 * PFR/TrueDoc-specific API.
44 *
45 * @description:
46 * This section contains the declaration of PFR-specific functions.
47 *
48 */
49
50
51 /**************************************************************************
52 *
53 * @function:
54 * FT_Get_PFR_Metrics
55 *
56 * @description:
57 * Return the outline and metrics resolutions of a given PFR face.
58 *
59 * @input:
60 * face ::
61 * 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` for
66 * non-PFR fonts. Optional (parameter can be `NULL`).
67 *
68 * ametrics_resolution ::
69 * Metrics resolution. This is equivalent to `outline_resolution` for
70 * 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 in
74 * metrics units to device subpixels. 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 ::
109 * A handle to the input face.
110 *
111 * left ::
112 * Index of the left glyph.
113 *
114 * right ::
115 * Index of the right glyph.
116 *
117 * @output:
118 * avector ::
119 * A kerning vector.
120 *
121 * @return:
122 * FreeType error code. 0~means success.
123 *
124 * @note:
125 * This function always return distances in original PFR metrics units.
126 * This is unlike @FT_Get_Kerning with the @FT_KERNING_UNSCALED mode,
127 * which always returns distances converted to outline units.
128 *
129 * You can use the value of the `x_scale` and `y_scale` parameters
130 * returned by @FT_Get_PFR_Metrics to scale these to device subpixels.
131 */
132 FT_EXPORT( FT_Error )
133 FT_Get_PFR_Kerning( FT_Face face,
134 FT_UInt left,
135 FT_UInt right,
136 FT_Vector *avector );
137
138
139 /**************************************************************************
140 *
141 * @function:
142 * FT_Get_PFR_Advance
143 *
144 * @description:
145 * Return a given glyph advance, expressed in original metrics units,
146 * from a PFR font.
147 *
148 * @input:
149 * face ::
150 * A handle to the input face.
151 *
152 * gindex ::
153 * The glyph index.
154 *
155 * @output:
156 * aadvance ::
157 * The glyph advance in metrics units.
158 *
159 * @return:
160 * FreeType error code. 0~means success.
161 *
162 * @note:
163 * You can use the `x_scale` or `y_scale` results of @FT_Get_PFR_Metrics
164 * to convert the advance to device subpixels (i.e., 1/64 of pixels).
165 */
166 FT_EXPORT( FT_Error )
167 FT_Get_PFR_Advance( FT_Face face,
168 FT_UInt gindex,
169 FT_Pos *aadvance );
170
171 /* */
172
173
174 FT_END_HEADER
175
176 #endif /* FTPFR_H_ */
177
178
179 /* END */