1/***************************************************************************/
2/* */
3/* ftmm.h */
4/* */
5/* FreeType Multiple Master font interface (specification). */
6/* */
7/* Copyright 1996-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 FTMM_H_
20#define FTMM_H_
21
22
23#include <ft2build.h>
24#include FT_TYPE1_TABLES_H
25
26
27FT_BEGIN_HEADER
28
29
30 /*************************************************************************/
31 /* */
32 /* <Section> */
33 /* multiple_masters */
34 /* */
35 /* <Title> */
36 /* Multiple Masters */
37 /* */
38 /* <Abstract> */
39 /* How to manage Multiple Masters fonts. */
40 /* */
41 /* <Description> */
42 /* The following types and functions are used to manage Multiple */
43 /* Master fonts, i.e., the selection of specific design instances by */
44 /* setting design axis coordinates. */
45 /* */
46 /* Besides Adobe MM fonts, the interface supports Apple's TrueType GX */
47 /* and OpenType variation fonts. Some of the routines only work with */
48 /* Adobe MM fonts, others will work with all three types. They are */
49 /* similar enough that a consistent interface makes sense. */
50 /* */
51 /*************************************************************************/
52
53
54 /*************************************************************************/
55 /* */
56 /* <Struct> */
57 /* FT_MM_Axis */
58 /* */
59 /* <Description> */
60 /* A structure to model a given axis in design space for Multiple */
61 /* Masters fonts. */
62 /* */
63 /* This structure can't be used for TrueType GX or OpenType variation */
64 /* fonts. */
65 /* */
66 /* <Fields> */
67 /* name :: The axis's name. */
68 /* */
69 /* minimum :: The axis's minimum design coordinate. */
70 /* */
71 /* maximum :: The axis's maximum design coordinate. */
72 /* */
73 typedef struct FT_MM_Axis_
74 {
75 FT_String* name;
76 FT_Long minimum;
77 FT_Long maximum;
78
79 } FT_MM_Axis;
80
81
82 /*************************************************************************/
83 /* */
84 /* <Struct> */
85 /* FT_Multi_Master */
86 /* */
87 /* <Description> */
88 /* A structure to model the axes and space of a Multiple Masters */
89 /* font. */
90 /* */
91 /* This structure can't be used for TrueType GX or OpenType variation */
92 /* fonts. */
93 /* */
94 /* <Fields> */
95 /* num_axis :: Number of axes. Cannot exceed~4. */
96 /* */
97 /* num_designs :: Number of designs; should be normally 2^num_axis */
98 /* even though the Type~1 specification strangely */
99 /* allows for intermediate designs to be present. */
100 /* This number cannot exceed~16. */
101 /* */
102 /* axis :: A table of axis descriptors. */
103 /* */
104 typedef struct FT_Multi_Master_
105 {
106 FT_UInt num_axis;
107 FT_UInt num_designs;
108 FT_MM_Axis axis[T1_MAX_MM_AXIS];
109
110 } FT_Multi_Master;
111
112
113 /*************************************************************************/
114 /* */
115 /* <Struct> */
116 /* FT_Var_Axis */
117 /* */
118 /* <Description> */
119 /* A structure to model a given axis in design space for Multiple */
120 /* Masters, TrueType GX, and OpenType variation fonts. */
121 /* */
122 /* <Fields> */
123 /* name :: The axis's name. */
124 /* Not always meaningful for TrueType GX or OpenType */
125 /* variation fonts. */
126 /* */
127 /* minimum :: The axis's minimum design coordinate. */
128 /* */
129 /* def :: The axis's default design coordinate. */
130 /* FreeType computes meaningful default values for Adobe */
131 /* MM fonts. */
132 /* */
133 /* maximum :: The axis's maximum design coordinate. */
134 /* */
135 /* tag :: The axis's tag (the equivalent to `name' for TrueType */
136 /* GX and OpenType variation fonts). FreeType provides */
137 /* default values for Adobe MM fonts if possible. */
138 /* */
139 /* strid :: The axis name entry in the font's `name' table. This */
140 /* is another (and often better) version of the `name' */
141 /* field for TrueType GX or OpenType variation fonts. Not */
142 /* meaningful for Adobe MM fonts. */
143 /* */
144 /* <Note> */
145 /* The fields `minimum', `def', and `maximum' are 16.16 fractional */
146 /* values for TrueType GX and OpenType variation fonts. For Adobe MM */
147 /* fonts, the values are integers. */
148 /* */
149 typedef struct FT_Var_Axis_
150 {
151 FT_String* name;
152
153 FT_Fixed minimum;
154 FT_Fixed def;
155 FT_Fixed maximum;
156
157 FT_ULong tag;
158 FT_UInt strid;
159
160 } FT_Var_Axis;
161
162
163 /*************************************************************************/
164 /* */
165 /* <Struct> */
166 /* FT_Var_Named_Style */
167 /* */
168 /* <Description> */
169 /* A structure to model a named instance in a TrueType GX or OpenType */
170 /* variation font. */
171 /* */
172 /* This structure can't be used for Adobe MM fonts. */
173 /* */
174 /* <Fields> */
175 /* coords :: The design coordinates for this instance. */
176 /* This is an array with one entry for each axis. */
177 /* */
178 /* strid :: The entry in `name' table identifying this instance. */
179 /* */
180 /* psid :: The entry in `name' table identifying a PostScript name */
181 /* for this instance. Value 0xFFFF indicates a missing */
182 /* entry. */
183 /* */
184 typedef struct FT_Var_Named_Style_
185 {
186 FT_Fixed* coords;
187 FT_UInt strid;
188 FT_UInt psid; /* since 2.7.1 */
189
190 } FT_Var_Named_Style;
191
192
193 /*************************************************************************/
194 /* */
195 /* <Struct> */
196 /* FT_MM_Var */
197 /* */
198 /* <Description> */
199 /* A structure to model the axes and space of an Adobe MM, TrueType */
200 /* GX, or OpenType variation font. */
201 /* */
202 /* Some fields are specific to one format and not to the others. */
203 /* */
204 /* <Fields> */
205 /* num_axis :: The number of axes. The maximum value is~4 for */
206 /* Adobe MM fonts; no limit in TrueType GX or */
207 /* OpenType variation fonts. */
208 /* */
209 /* num_designs :: The number of designs; should be normally */
210 /* 2^num_axis for Adobe MM fonts. Not meaningful */
211 /* for TrueType GX or OpenType variation fonts */
212 /* (where every glyph could have a different */
213 /* number of designs). */
214 /* */
215 /* num_namedstyles :: The number of named styles; a `named style' is */
216 /* a tuple of design coordinates that has a string */
217 /* ID (in the `name' table) associated with it. */
218 /* The font can tell the user that, for example, */
219 /* [Weight=1.5,Width=1.1] is `Bold'. Another name */
220 /* for `named style' is `named instance'. */
221 /* */
222 /* For Adobe Multiple Masters fonts, this value is */
223 /* always zero because the format does not support */
224 /* named styles. */
225 /* */
226 /* axis :: An axis descriptor table. */
227 /* TrueType GX and OpenType variation fonts */
228 /* contain slightly more data than Adobe MM fonts. */
229 /* Memory management of this pointer is done */
230 /* internally by FreeType. */
231 /* */
232 /* namedstyle :: A named style (instance) table. */
233 /* Only meaningful for TrueType GX and OpenType */
234 /* variation fonts. Memory management of this */
235 /* pointer is done internally by FreeType. */
236 /* */
237 typedef struct FT_MM_Var_
238 {
239 FT_UInt num_axis;
240 FT_UInt num_designs;
241 FT_UInt num_namedstyles;
242 FT_Var_Axis* axis;
243 FT_Var_Named_Style* namedstyle;
244
245 } FT_MM_Var;
246
247
248 /*************************************************************************/
249 /* */
250 /* <Function> */
251 /* FT_Get_Multi_Master */
252 /* */
253 /* <Description> */
254 /* Retrieve a variation descriptor of a given Adobe MM font. */
255 /* */
256 /* This function can't be used with TrueType GX or OpenType variation */
257 /* fonts. */
258 /* */
259 /* <Input> */
260 /* face :: A handle to the source face. */
261 /* */
262 /* <Output> */
263 /* amaster :: The Multiple Masters descriptor. */
264 /* */
265 /* <Return> */
266 /* FreeType error code. 0~means success. */
267 /* */
268 FT_EXPORT( FT_Error )
269 FT_Get_Multi_Master( FT_Face face,
270 FT_Multi_Master *amaster );
271
272
273 /*************************************************************************/
274 /* */
275 /* <Function> */
276 /* FT_Get_MM_Var */
277 /* */
278 /* <Description> */
279 /* Retrieve a variation descriptor for a given font. */
280 /* */
281 /* This function works with all supported variation formats. */
282 /* */
283 /* <Input> */
284 /* face :: A handle to the source face. */
285 /* */
286 /* <Output> */
287 /* amaster :: The variation descriptor. */
288 /* Allocates a data structure, which the user must */
289 /* deallocate with a call to @FT_Done_MM_Var after use. */
290 /* */
291 /* <Return> */
292 /* FreeType error code. 0~means success. */
293 /* */
294 FT_EXPORT( FT_Error )
295 FT_Get_MM_Var( FT_Face face,
296 FT_MM_Var* *amaster );
297
298
299 /*************************************************************************/
300 /* */
301 /* <Function> */
302 /* FT_Done_MM_Var */
303 /* */
304 /* <Description> */
305 /* Free the memory allocated by @FT_Get_MM_Var. */
306 /* */
307 /* <Input> */
308 /* library :: A handle of the face's parent library object that was */
309 /* used in the call to @FT_Get_MM_Var to create `amaster'. */
310 /* */
311 /* <Return> */
312 /* FreeType error code. 0~means success. */
313 /* */
314 FT_EXPORT( FT_Error )
315 FT_Done_MM_Var( FT_Library library,
316 FT_MM_Var *amaster );
317
318
319 /*************************************************************************/
320 /* */
321 /* <Function> */
322 /* FT_Set_MM_Design_Coordinates */
323 /* */
324 /* <Description> */
325 /* For Adobe MM fonts, choose an interpolated font design through */
326 /* design coordinates. */
327 /* */
328 /* This function can't be used with TrueType GX or OpenType variation */
329 /* fonts. */
330 /* */
331 /* <InOut> */
332 /* face :: A handle to the source face. */
333 /* */
334 /* <Input> */
335 /* num_coords :: The number of available design coordinates. If it */
336 /* is larger than the number of axes, ignore the excess */
337 /* values. If it is smaller than the number of axes, */
338 /* use default values for the remaining axes. */
339 /* */
340 /* coords :: An array of design coordinates. */
341 /* */
342 /* <Return> */
343 /* FreeType error code. 0~means success. */
344 /* */
345 /* <Note> */
346 /* [Since 2.8.1] To reset all axes to the default values, call the */
347 /* function with `num_coords' set to zero and `coords' set to NULL. */
348 /* */
349 /* [Since 2.9] If `num_coords' is larger than zero, this function */
350 /* sets the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags' */
351 /* field (i.e., @FT_IS_VARIATION will return true). If `num_coords' */
352 /* is zero, this bit flag gets unset. */
353 /* */
354 FT_EXPORT( FT_Error )
355 FT_Set_MM_Design_Coordinates( FT_Face face,
356 FT_UInt num_coords,
357 FT_Long* coords );
358
359
360 /*************************************************************************/
361 /* */
362 /* <Function> */
363 /* FT_Set_Var_Design_Coordinates */
364 /* */
365 /* <Description> */
366 /* Choose an interpolated font design through design coordinates. */
367 /* */
368 /* This function works with all supported variation formats. */
369 /* */
370 /* <InOut> */
371 /* face :: A handle to the source face. */
372 /* */
373 /* <Input> */
374 /* num_coords :: The number of available design coordinates. If it */
375 /* is larger than the number of axes, ignore the excess */
376 /* values. If it is smaller than the number of axes, */
377 /* use default values for the remaining axes. */
378 /* */
379 /* coords :: An array of design coordinates. */
380 /* */
381 /* <Return> */
382 /* FreeType error code. 0~means success. */
383 /* */
384 /* <Note> */
385 /* [Since 2.8.1] To reset all axes to the default values, call the */
386 /* function with `num_coords' set to zero and `coords' set to NULL. */
387 /* [Since 2.9] `Default values' means the currently selected named */
388 /* instance (or the base font if no named instance is selected). */
389 /* */
390 /* [Since 2.9] If `num_coords' is larger than zero, this function */
391 /* sets the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags' */
392 /* field (i.e., @FT_IS_VARIATION will return true). If `num_coords' */
393 /* is zero, this bit flag gets unset. */
394 /* */
395 FT_EXPORT( FT_Error )
396 FT_Set_Var_Design_Coordinates( FT_Face face,
397 FT_UInt num_coords,
398 FT_Fixed* coords );
399
400
401 /*************************************************************************/
402 /* */
403 /* <Function> */
404 /* FT_Get_Var_Design_Coordinates */
405 /* */
406 /* <Description> */
407 /* Get the design coordinates of the currently selected interpolated */
408 /* font. */
409 /* */
410 /* This function works with all supported variation formats. */
411 /* */
412 /* <Input> */
413 /* face :: A handle to the source face. */
414 /* */
415 /* num_coords :: The number of design coordinates to retrieve. If it */
416 /* is larger than the number of axes, set the excess */
417 /* values to~0. */
418 /* */
419 /* <Output> */
420 /* coords :: The design coordinates array. */
421 /* */
422 /* <Return> */
423 /* FreeType error code. 0~means success. */
424 /* */
425 /* <Since> */
426 /* 2.7.1 */
427 /* */
428 FT_EXPORT( FT_Error )
429 FT_Get_Var_Design_Coordinates( FT_Face face,
430 FT_UInt num_coords,
431 FT_Fixed* coords );
432
433
434 /*************************************************************************/
435 /* */
436 /* <Function> */
437 /* FT_Set_MM_Blend_Coordinates */
438 /* */
439 /* <Description> */
440 /* Choose an interpolated font design through normalized blend */
441 /* coordinates. */
442 /* */
443 /* This function works with all supported variation formats. */
444 /* */
445 /* <InOut> */
446 /* face :: A handle to the source face. */
447 /* */
448 /* <Input> */
449 /* num_coords :: The number of available design coordinates. If it */
450 /* is larger than the number of axes, ignore the excess */
451 /* values. If it is smaller than the number of axes, */
452 /* use default values for the remaining axes. */
453 /* */
454 /* coords :: The design coordinates array (each element must be */
455 /* between 0 and 1.0 for Adobe MM fonts, and between */
456 /* -1.0 and 1.0 for TrueType GX and OpenType variation */
457 /* fonts). */
458 /* */
459 /* <Return> */
460 /* FreeType error code. 0~means success. */
461 /* */
462 /* <Note> */
463 /* [Since 2.8.1] To reset all axes to the default values, call the */
464 /* function with `num_coords' set to zero and `coords' set to NULL. */
465 /* [Since 2.9] `Default values' means the currently selected named */
466 /* instance (or the base font if no named instance is selected). */
467 /* */
468 /* [Since 2.9] If `num_coords' is larger than zero, this function */
469 /* sets the @FT_FACE_FLAG_VARIATION bit in @FT_Face's `face_flags' */
470 /* field (i.e., @FT_IS_VARIATION will return true). If `num_coords' */
471 /* is zero, this bit flag gets unset. */
472 /* */
473 FT_EXPORT( FT_Error )
474 FT_Set_MM_Blend_Coordinates( FT_Face face,
475 FT_UInt num_coords,
476 FT_Fixed* coords );
477
478
479 /*************************************************************************/
480 /* */
481 /* <Function> */
482 /* FT_Get_MM_Blend_Coordinates */
483 /* */
484 /* <Description> */
485 /* Get the normalized blend coordinates of the currently selected */
486 /* interpolated font. */
487 /* */
488 /* This function works with all supported variation formats. */
489 /* */
490 /* <Input> */
491 /* face :: A handle to the source face. */
492 /* */
493 /* num_coords :: The number of normalized blend coordinates to */
494 /* retrieve. If it is larger than the number of axes, */
495 /* set the excess values to~0.5 for Adobe MM fonts, and */
496 /* to~0 for TrueType GX and OpenType variation fonts. */
497 /* */
498 /* <Output> */
499 /* coords :: The normalized blend coordinates array. */
500 /* */
501 /* <Return> */
502 /* FreeType error code. 0~means success. */
503 /* */
504 /* <Since> */
505 /* 2.7.1 */
506 /* */
507 FT_EXPORT( FT_Error )
508 FT_Get_MM_Blend_Coordinates( FT_Face face,
509 FT_UInt num_coords,
510 FT_Fixed* coords );
511
512
513 /*************************************************************************/
514 /* */
515 /* <Function> */
516 /* FT_Set_Var_Blend_Coordinates */
517 /* */
518 /* <Description> */
519 /* This is another name of @FT_Set_MM_Blend_Coordinates. */
520 /* */
521 FT_EXPORT( FT_Error )
522 FT_Set_Var_Blend_Coordinates( FT_Face face,
523 FT_UInt num_coords,
524 FT_Fixed* coords );
525
526
527 /*************************************************************************/
528 /* */
529 /* <Function> */
530 /* FT_Get_Var_Blend_Coordinates */
531 /* */
532 /* <Description> */
533 /* This is another name of @FT_Get_MM_Blend_Coordinates. */
534 /* */
535 /* <Since> */
536 /* 2.7.1 */
537 /* */
538 FT_EXPORT( FT_Error )
539 FT_Get_Var_Blend_Coordinates( FT_Face face,
540 FT_UInt num_coords,
541 FT_Fixed* coords );
542
543
544 /*************************************************************************/
545 /* */
546 /* <Enum> */
547 /* FT_VAR_AXIS_FLAG_XXX */
548 /* */
549 /* <Description> */
550 /* A list of bit flags used in the return value of */
551 /* @FT_Get_Var_Axis_Flags. */
552 /* */
553 /* <Values> */
554 /* FT_VAR_AXIS_FLAG_HIDDEN :: */
555 /* The variation axis should not be exposed to user interfaces. */
556 /* */
557 /* <Since> */
558 /* 2.8.1 */
559 /* */
560#define FT_VAR_AXIS_FLAG_HIDDEN 1
561
562
563 /*************************************************************************/
564 /* */
565 /* <Function> */
566 /* FT_Get_Var_Axis_Flags */
567 /* */
568 /* <Description> */
569 /* Get the `flags' field of an OpenType Variation Axis Record. */
570 /* */
571 /* Not meaningful for Adobe MM fonts (`*flags' is always zero). */
572 /* */
573 /* <Input> */
574 /* master :: The variation descriptor. */
575 /* */
576 /* axis_index :: The index of the requested variation axis. */
577 /* */
578 /* <Output> */
579 /* flags :: The `flags' field. See @FT_VAR_AXIS_FLAG_XXX for */
580 /* possible values. */
581 /* */
582 /* <Return> */
583 /* FreeType error code. 0~means success. */
584 /* */
585 /* <Since> */
586 /* 2.8.1 */
587 /* */
588 FT_EXPORT( FT_Error )
589 FT_Get_Var_Axis_Flags( FT_MM_Var* master,
590 FT_UInt axis_index,
591 FT_UInt* flags );
592
593
594 /*************************************************************************/
595 /* */
596 /* <Function> */
597 /* FT_Set_Named_Instance */
598 /* */
599 /* <Description> */
600 /* Set or change the current named instance. */
601 /* */
602 /* <Input> */
603 /* face :: A handle to the source face. */
604 /* */
605 /* instance_index :: The index of the requested instance, starting */
606 /* with value 1. If set to value 0, FreeType */
607 /* switches to font access without a named */
608 /* instance. */
609 /* */
610 /* <Return> */
611 /* FreeType error code. 0~means success. */
612 /* */
613 /* <Note> */
614 /* The function uses the value of `instance_index' to set bits 16-30 */
615 /* of the face's `face_index' field. It also resets any variation */
616 /* applied to the font, and the @FT_FACE_FLAG_VARIATION bit of the */
617 /* face's `face_flags' field gets reset to zero (i.e., */
618 /* @FT_IS_VARIATION will return false). */
619 /* */
620 /* For Adobe MM fonts (which don't have named instances) this */
621 /* function simply resets the current face to the default instance. */
622 /* */
623 /* <Since> */
624 /* 2.9 */
625 /* */
626 FT_EXPORT( FT_Error )
627 FT_Set_Named_Instance( FT_Face face,
628 FT_UInt instance_index );
629
630 /* */
631
632
633FT_END_HEADER
634
635#endif /* FTMM_H_ */
636
637
638/* END */
639