1 /****************************************************************************
2 *
3 * ftmac.h
4 *
5 * Additional Mac-specific API.
6 *
7 * Copyright (C) 1996-2023 by
8 * Just van Rossum, 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 /****************************************************************************
20 *
21 * NOTE: Include this file after `FT_FREETYPE_H` and after any
22 * Mac-specific headers (because this header uses Mac types such as
23 * 'Handle', 'FSSpec', 'FSRef', etc.)
24 *
25 */
26
27
28 #ifndef FTMAC_H_
29 #define FTMAC_H_
30
31
32
33
34 FT_BEGIN_HEADER
35
36
37 /* gcc-3.1 and later can warn about functions tagged as deprecated */
38 #ifndef FT_DEPRECATED_ATTRIBUTE
39 #if defined( __GNUC__ ) && \
40 ( ( __GNUC__ >= 4 ) || \
41 ( ( __GNUC__ == 3 ) && ( __GNUC_MINOR__ >= 1 ) ) )
42 #define FT_DEPRECATED_ATTRIBUTE __attribute__(( deprecated ))
43 #else
44 #define FT_DEPRECATED_ATTRIBUTE
45 #endif
46 #endif
47
48
49 /**************************************************************************
50 *
51 * @section:
52 * mac_specific
53 *
54 * @title:
55 * Mac Specific Interface
56 *
57 * @abstract:
58 * Only available on the Macintosh.
59 *
60 * @description:
61 * The following definitions are only available if FreeType is compiled
62 * on a Macintosh.
63 *
64 */
65
66
67 /**************************************************************************
68 *
69 * @function:
70 * FT_New_Face_From_FOND
71 *
72 * @description:
73 * Create a new face object from a FOND resource.
74 *
75 * @inout:
76 * library ::
77 * A handle to the library resource.
78 *
79 * @input:
80 * fond ::
81 * A FOND resource.
82 *
83 * face_index ::
84 * Only supported for the -1 'sanity check' special case.
85 *
86 * @output:
87 * aface ::
88 * A handle to a new face object.
89 *
90 * @return:
91 * FreeType error code. 0~means success.
92 *
93 * @example:
94 * This function can be used to create @FT_Face objects from fonts that
95 * are installed in the system as follows.
96 *
97 * ```
98 * fond = GetResource( 'FOND', fontName );
99 * error = FT_New_Face_From_FOND( library, fond, 0, &face );
100 * ```
101 */
102 FT_EXPORT( FT_Error )
103 FT_New_Face_From_FOND( FT_Library library,
104 Handle fond,
105 FT_Long face_index,
106 FT_Face *aface )
107 FT_DEPRECATED_ATTRIBUTE;
108
109
110 /**************************************************************************
111 *
112 * @function:
113 * FT_GetFile_From_Mac_Name
114 *
115 * @description:
116 * Return an FSSpec for the disk file containing the named font.
117 *
118 * @input:
119 * fontName ::
120 * Mac OS name of the font (e.g., Times New Roman Bold).
121 *
122 * @output:
123 * pathSpec ::
124 * FSSpec to the file. For passing to @FT_New_Face_From_FSSpec.
125 *
126 * face_index ::
127 * Index of the face. For passing to @FT_New_Face_From_FSSpec.
128 *
129 * @return:
130 * FreeType error code. 0~means success.
131 */
132 FT_EXPORT( FT_Error )
133 FT_GetFile_From_Mac_Name( const char* fontName,
134 FSSpec* pathSpec,
135 FT_Long* face_index )
136 FT_DEPRECATED_ATTRIBUTE;
137
138
139 /**************************************************************************
140 *
141 * @function:
142 * FT_GetFile_From_Mac_ATS_Name
143 *
144 * @description:
145 * Return an FSSpec for the disk file containing the named font.
146 *
147 * @input:
148 * fontName ::
149 * Mac OS name of the font in ATS framework.
150 *
151 * @output:
152 * pathSpec ::
153 * FSSpec to the file. For passing to @FT_New_Face_From_FSSpec.
154 *
155 * face_index ::
156 * Index of the face. For passing to @FT_New_Face_From_FSSpec.
157 *
158 * @return:
159 * FreeType error code. 0~means success.
160 */
161 FT_EXPORT( FT_Error )
162 FT_GetFile_From_Mac_ATS_Name( const char* fontName,
163 FSSpec* pathSpec,
164 FT_Long* face_index )
165 FT_DEPRECATED_ATTRIBUTE;
166
167
168 /**************************************************************************
169 *
170 * @function:
171 * FT_GetFilePath_From_Mac_ATS_Name
172 *
173 * @description:
174 * Return a pathname of the disk file and face index for given font name
175 * that is handled by ATS framework.
176 *
177 * @input:
178 * fontName ::
179 * Mac OS name of the font in ATS framework.
180 *
181 * @output:
182 * path ::
183 * Buffer to store pathname of the file. For passing to @FT_New_Face.
184 * The client must allocate this buffer before calling this function.
185 *
186 * maxPathSize ::
187 * Lengths of the buffer `path` that client allocated.
188 *
189 * face_index ::
190 * Index of the face. For passing to @FT_New_Face.
191 *
192 * @return:
193 * FreeType error code. 0~means success.
194 */
195 FT_EXPORT( FT_Error )
196 FT_GetFilePath_From_Mac_ATS_Name( const char* fontName,
197 UInt8* path,
198 UInt32 maxPathSize,
199 FT_Long* face_index )
200 FT_DEPRECATED_ATTRIBUTE;
201
202
203 /**************************************************************************
204 *
205 * @function:
206 * FT_New_Face_From_FSSpec
207 *
208 * @description:
209 * Create a new face object from a given resource and typeface index
210 * using an FSSpec to the font file.
211 *
212 * @inout:
213 * library ::
214 * A handle to the library resource.
215 *
216 * @input:
217 * spec ::
218 * FSSpec to the font file.
219 *
220 * face_index ::
221 * The index of the face within the resource. The first face has
222 * index~0.
223 * @output:
224 * aface ::
225 * A handle to a new face object.
226 *
227 * @return:
228 * FreeType error code. 0~means success.
229 *
230 * @note:
231 * @FT_New_Face_From_FSSpec is identical to @FT_New_Face except it
232 * accepts an FSSpec instead of a path.
233 */
234 FT_EXPORT( FT_Error )
235 FT_New_Face_From_FSSpec( FT_Library library,
236 const FSSpec *spec,
237 FT_Long face_index,
238 FT_Face *aface )
239 FT_DEPRECATED_ATTRIBUTE;
240
241
242 /**************************************************************************
243 *
244 * @function:
245 * FT_New_Face_From_FSRef
246 *
247 * @description:
248 * Create a new face object from a given resource and typeface index
249 * using an FSRef to the font file.
250 *
251 * @inout:
252 * library ::
253 * A handle to the library resource.
254 *
255 * @input:
256 * spec ::
257 * FSRef to the font file.
258 *
259 * face_index ::
260 * The index of the face within the resource. The first face has
261 * index~0.
262 * @output:
263 * aface ::
264 * A handle to a new face object.
265 *
266 * @return:
267 * FreeType error code. 0~means success.
268 *
269 * @note:
270 * @FT_New_Face_From_FSRef is identical to @FT_New_Face except it accepts
271 * an FSRef instead of a path.
272 */
273 FT_EXPORT( FT_Error )
274 FT_New_Face_From_FSRef( FT_Library library,
275 const FSRef *ref,
276 FT_Long face_index,
277 FT_Face *aface )
278 FT_DEPRECATED_ATTRIBUTE;
279
280 /* */
281
282
283 FT_END_HEADER
284
285
286 #endif /* FTMAC_H_ */
287
288
289 /* END */